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About This Book 

This book describes the IBM® RISCWatch™ Debugger, its windowing 
environment, and its debugging facilities and commands. This publication 
contains the information needed to use RISCWatch, a hardware and software 
development tool for PowerPC™ processors. 

The RISCWatch Debugger supports numerous PowerPC processors and 
versions. For more information on current processors supported and other up to 
date information, please refer to the README file included with the product, or 
visit our web site at http://www.chips.ibm.com/products/embedded/riscwtch 

Support for additional PowerPC processors and targets is planned for future 
RISCWatch releases. 


Who Should Use This Book 

This book is for: 

• Programmers and engineers who will use the RISCWatch Debugger to develop 
embedded applications using PowerPC processors 

Users should understand: 

• Functions, architecture, and features of their host systems 

• PowerPC instruction set architecture and assembler programming 

• C programming 

For information concerning features and operations of a specific PowerPC 
processor, please refer to the document set for each individual device. 


How To Use This Book 

This manual describes the RISCWatch debugger facilities, windows, and functions 
provided specifically to support PowerPC processors in embedded applications. 
This book is divided into the following chapters: 

• Chapter 1, "Introducing the RISCWatch Debugger," describes RISCWatch 
debugger functions and features. 

• Chapter 2, "Quick Start," introduces the RISCWatch Debugger by means of a 
brief demo with descriptions of the main windows and debugger functions. 
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• Chapter 3, "Using the RISCWatch Debugger," shows debugging tasks in 
relation to sample debugger windows and some specific features of the 
debugger. 

• Chapter 4, "Using Processor-Specific Debug Features," describes RISCWatch 
features and windows applicable to specific PowerPC processors. 

• Chapter 5, "Debugger Command Reference," provides detailed descriptions of 
the debugger commands. 

• Appendix A, "Interfacing RISCWatch to a Target Board," describes the required 
connections for interfacing RISCWatch to a PowerPC processor on a target 
development board. 

• Appendix B, “Register Definition File (Outdate),” describes the file format for 
the Register Definition File (RDF) which is used to add custom register 
definitions to the RISCWatch debugger. 

For detailed information about installing and configuring the RISCWatch 
Debugger, consult the accompanying RISCWatch Debugger Installation Guide. 

Conventions Used In This Book 

This book follows numeric and highlighting notation conventions based on those 
used in the RISC System/6000™ and Advanced Interactive Executive (AIX™) 
publications. 

Numeric Notation and Input Conventions 

In general, numbers are used exactly as shown. Unless noted otherwise, all 
numbers are in decimal, and, if entered as part of a command, are entered 
without format information. 

The hexadecimal digits A through F typically appear in uppercase. Hexadecimal 
numbers are preceded by “Ox” as shown below: 

0x1 A7 

Highlighting Conventions 

In code examples, this book uses no highlighting. 

This book uses the following highlighting conventions: 

• The names of invariant objects known to RISCWatch appear in bold type. In 
some text, however, such as in lists, no special typographic treatment is used. 
Examples of such objects include: 

• File and command names 

• Data types and structures 
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• Constants and flags 

• Variable names that are supplied by user programs appear in italic type. In 
some text, however, such as in lists, no special typographic treatment is used. 
Examples of these objects include arguments and other parameters. 

Names of objects and keywords known to the RISCWatch Debugger must be 
entered exactly as written. 


Syntax Diagram Conventions 


Throughout this book, diagrams illustrate the syntax for string formats and 
commands. The following list shows how to read these diagrams: 

• Read the syntax diagrams from left to right, from top to bottom, following the 
path of the line. 

• -symbol begins a diagram. 

• A-► symbol indicates continuation of a diagram on the next line. 

• A »» symbol indicates continuation of a diagram from the previous line. 

• A-symbol terminates a diagram. 

• Keywords are in regular type, and variables are in italics. Keywords must be 
typed exactly as shown. 

• Keywords or variables on the main path of a diagram are required. 

— keyword - variable 1 — variable2 -► -* 


Keywords or variables shown on branches below the main path are optional. 
» » keyword 


L variablel -I L variable2 


• Keywords or variables can appear in a stack, indicating that only one item in a 
stack can be chosen. If an item in a stack is on the main path, you must choose 
an item from the stack. If all items in a stack are below the main path, you may 
choose an item from the stack. 


For example, in the following syntax diagram, you must choose either variablel 
or variable2. However, because variable3 and variable4 are below the main 
path, neither is required. 


— keyword 


—j- variablel 
L variable2 -I 


\- variable3 -\ 


L variable4 J 
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A repeat separator is a returning arrow that surrounds a syntax element or 
group and shows that the element or group can be repeated. 


keyword 


variable 1 


Where to Find More information 

The following sections list sources of information about or related to RISCWatch. 

Related IBM Publications 

This book refers to the following publications, which are available from your IBM 
Microelectronics representative: 

• RISC System/6000 Publications 

IBM RISC System/6000: POWERstation and POWERserver Hardware Technical 
Information General Architectures, SA23-2643 

• AIX Publications 

This book refers to the following AIX publications. The words “IBM AIX Version 4 
for RISC System/6000” are actually part of the title of each book; however, in all 
references to these books, those words are omitted. 

Assembler Language Reference, SC23-2642 

Commands Reference, Volume 1, SC23-2537 

Commands Reference, Volume 2, SC23-2538 

Commands Reference, Volume 3, SC23-2539 

Commands Reference, Volume 4, SC23-2540 

Commands Reference, Volume 5, SC23-2639 

Commands Reference, Volume 6, SC23-2640 

Editing Concepts and Procedures, GC23-2212 

Files Reference, GC23-2200 

• XL C Compiler/6000 Publications 
XL C Language Reference, SC09-1260 
XL C User’s Guide, SC09-1259 

• IBM High C/C++ Publications 
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The following list includes the books in the IBM High C/C++ library: 

IBM High C/C++ Programmer's Guide for PowerPC, 92G6920 
IBM High C/C++ Language Reference for PowerPC, 92G6923 
IBM ELF Assembler User's Guide for PowerPC, 92G6921 
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Chapter 1. Introducing the RISCWatch Debugger 

The IBM RISCWatch Debugger provides a powerful, flexible debugging 
environment to support hardware and software development using PowerPC 
processors in embedded applications. 


Embedded System Software Development 

Embedded systems are typically developed in a cross-development environment 
consisting of host computers and target systems. The host computers provide 
software and project management tools for embedded system application 
developers. The developers are not restricted to the limited computing resources 
typically available on the target embedded system. 

Developers write, compile, and debug embedded application programs on the 
host computers. When appropriate, the application programs are loaded on the 
target embedded system, where they run and are tested in the target operating 
environment. 

Embedded system development is an iterative process; the application programs 
are refined on the host computers and tested on the target system until the 
programs meet the functional and performance requirements of the application. 
Eventually, the application programs are shipped as part of an embedded system. 

Programming Languages 

Application programs for PowerPC processors are typically written in C/C++ and 
assembler. Formats currently supported include ELF/DWARF (SVR4 ABI and 
PowerPC Embedded ABI) and XCOFF/STABS. 


Features 


RISCWatch is a development and debug tool for PowerPC processors. 
RISCWatch employs a graphical user interface allowing complete access to all of 
the PowerPC processor functions. Following is a list of RISCWatch features: 

• Robust source program debug capability 

• Low-level hardware program debug (assembly level) 

• Read, modify and write of all processor registers 

• Read, modify and write of processor register fields 
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• User defined registers (DCR, SPR, Memory mapped) 

• Read, modify and write of all processor memory (single, multi-byte access) 
with memory fill and write verification testing 

• Memory loading of many types of file formats (ELF, XCOFF, Motorola 32-bit, 
and straight binary) 

• Save/load processor memory image to/from file 

• Save/load processor register values to/from file 

• Command file execution, including nesting capabilities 

• Command file execution with user-created variables, programming 
constructs, expressions and printf-like function 

• Command file single-step execution 

• Batch mode command file execution 

• Program assembler and disassembler allowing memory read and write 
capability 

• Single-step execution (assembly or source level) of loaded programs 

• Set/clear of multiple-event breakpoints 

• Saving and loading of customized window layout 

• User-defined windows consisting of register, register field, memory, 
disassembly, command execution and status interfaces 

• Processor reset functions 

• Logging of all commands and messages 

• File browsing 

• Operating System command execution capability 

• On-line help for all screens including extensive processor register definitions 

• Multiprocessor support with User-defined board configurations 

• Resizable windows with configurable user interface control colors 

• User-defined Core+ASIC interface for customized chip support 

• RISCTrace interface for PowerPC 400Series real-time trace debug 
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Chapter 2. Quick Start 

Included with the RISCWatch debugger are some example files that can be used 
to quickly demonstrate some of the capabilities of the tool. They include all of the 
source, object, and executable files necessary to proceed with the following 
tutorial. The sections are designed to be performed sequentially, but the actions 
described in each can be applied at various stages of the debug session. 

In general, the windows and descriptions will appear exactly as stated in the text. 
However, there may be slight differences in what is pictured versus what the user 
will actually see when running through the demonstration. For example, if the 
program is loaded in a location other than that specified in the load command, 
any addresses shown in the window might not match what appears in the 
document. However, the functions performed are equivalent. 


Starting the Debugger 

1=1 ' RISCWatch 


File Source Hardware Window Utilities Help 



Welcome to RISCWatch v4.00 

No MPS 

403GC 

JTAG 

STOPPED 


Figure 2-1. Sample Main Window 

The Main Window, as illustrated in figure 2.1, is the first window seen when 
RISCWatch is started. Perform the following steps to display this window: 
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• Edit the “rwppc.env” file to designate the “target processor”, “target type”, 
“target name”, and RISCWatch directory, as described in “Environment 
Resources” on page 3-5 and “Invoking the Debugger” on page 3-33. Edit any 
additional environment resources required for your specific setup. 

• From a RISC System/6000 or Sun workstation running Motif, change to the 
installation directory, and type “rwppc”. 

• From a PC running Windows, double-click on the RISCWatch icon created 
during program installation. 


Entering Commands 

To enter debugger commands from the command line of the Main window, 
single-click on the Command area to give it ‘focus’, type in the desired command, 
and then press “Enter”. See “Command Quick Reference” on page 5-4 for the 
complete list of valid commands. 

For the demonstration program, enter the command “srchpath set xxxx”, where 
xxxx is the fully qualified directory path where the examples reside. 

Note that when the command is entered, it is displayed in the command history 
window. It is also displayed, along with any associated messages, below the 
command line in the message window. 


Loading the Demo Program 

Enter from the command line: 

load file demo t=0x35000 d=0x37000 

Note: An address of 0x35000 will work for most ROM Monitor targets. Refer to 
the Eval Kit User’s Guide (section 7.5) for instructions on how a valid address can 
be determined for ROM Monitor targets. 
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Scrolling Through Source Code 


Files 


1 “ ■ 


demol.c 
demo2.c 


Hide Help 


Figure 2-2. Sample Files Window 

Now that the program has been loaded, the next step is to bring up the source 
files. Move the cursor to the to the “Source” menu bar entry on the Main screen 
and single click the left mouse button. Then, single click on the “Files” choice. 
Figure 2-2 shows the sample Files display. 

Move the cursor to the to the “Source” menu bar entry on the Main screen and 
single click the left mouse button. Then, single click on the “Source” choice. The 
Source window should be displayed. 

Single-click the left mouse button on the “demol .c” entry in the Files window. It 
will become highlighted, and the following will appear in the Source Window: 
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Source (/sld/rwppc/regress/src /demo 1 ,c ) 



1 



2 



3 

int glob=0; 


4 

int glob2=0; 


5 



6 

void routine2(void); 


7 

void routine3(void); 


8 

void routine4(void); 


9 

void routine5(void); 


10 



11 

typedef struct inside 


12 

£ 


13 

int count; 


14 

char nameClOl; 


15 

J; 


16 



17 

typedef struct Struct_Outer 


18 

£ 


19 

struct inside show_in; 


20 

union £ 


21 

struct £ 


22 

int Int_type; 


23 

char Str_type £31; 


24 

} var_l; 


25 

struct £ 


26 

char Str_2_Comp £31; 


STOPPED 


u ..------- "---■> 




Run | lin* | Call jtap | Ret step | Asm step | 

r 


^ Source 

Restart | Show IP | Hide | Help 


Source/Asm 


Figure 2-3. Sample Source Window 

Move the cursor to the Main window, and single-click the left mouse button in the 
Command area to enable the command line. 

Enter “pagedn source” on the command line. The source window will scroll down 
one page. 

Enter “pageup” on the command line. The source window will scroll up one page. 
Notice that “source” wasn’t specified this time because the last command stored it 
for subsequent commands to use. 

Move the cursor back to the Source window, and place the cursor on the down 
arrow found on the scroll bar area on the right side of the window. Hold down the 
left mouse button. The source code will scroll down a line at a time while the 
button is being held down. The scroll bar will also move down along the right side 
of the screen. 

Move the cursor to the area above the scroll bar, placing it between the bar and 
the up arrow. Press the left mouse button once. This will move the source code up 
one page. 
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Move the cursor to the scroll bar itself. Hold down the left mouse button and move 
the mouse up and down. The source code will scroll up and down with the 
movement of the mouse. 

Move the cursor back to the Main window, and single-click the left mouse button in 
the Command area to enable the command line. 

Enter “top” on the command line. The Source window will scroll to the top of the 
source file. 


Setting Breakpoints 

Move the cursor back to the Source window, and scroll down through the code 
until line 39 is in view. 

Single-click the left mouse button, in the Source window left side which shows the 
line numbers, at the line 39 entry. A “BP” indicator will appear next to the line 
number 39. This means a breakpoint has been set. 

Move the cursor to the to the “Source” menu bar entry on the Main screen and 
single-click the left mouse button. Then, single-click on the “Breakpoints” option. 
Figure 2-4 shows the display. 


— 

Breakpoints 

l 




S ; 0x0000A094 ; main ; demol.c ; 00039 ; /sld/rwp 

M 

U 

Cl 



Breakpoint mode 

Software BPs 

OHardware BPs 

OHardStep BPs 

1^-' 

iS*I*t* | Delete fill 

Hide Help_ 


Figure 2-4. Sample Breakpoints Window 
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Various information about the breakpoint is displayed in the Breakpoints window, 
including type (hardware or software), address, function name, source file, and 
line number corresponding to the breakpoint. 

Move the cursor button over the entry in the Breakpoints window and single-click 
the left mouse button. The entry is highlighted, and its corresponding location in 
the Source window is highlighted. The Delete button is also enabled. 

Single-click the left mouse button again on the entry. The highlight is removed, 
and the Delete button is disabled. 

Move the cursor to the to the “Source” menu bar entry on the Main screen and 
single click the left mouse button. Then, single click the left mouse button on the 
“Functions” option. Figure 2-5 shows the display. 


Functions 


JQ 


main; 0x0000A078; demol,c 

routine2; 

0x00008218; 

demo2,c 

routine3; 

0x0000A12C; 

demol♦c 

routine4; 

0x0000A180; 

demol♦c 


—Functions display mode 

Functions w/ debug info by name 
v- Functions w/ debug info by addr. 
v^All functions by name 
vAll functions by addr. 


Hide 

Help 


Figure 2-5. Sample Functions Window 


Locate the entry “routine2; demo2.c”. Move the cursor to this entry, and 
single-click the left mouse button. The source file containing routine2 (demo2.c) 
will now be shown in the Source window, and the entry will be highlighted in the 
Functions window. 

Double-click the left mouse button in the Functions widow at the line 
corresponding to the “routine2; demo2.c” function entry. This will set a breakpoint 
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at the beginning of the routine2 function. The “BP” indicator will appear in the 
Source window at the first executable line in the function. Information about the 
breakpoint will also appear in the Breakpoints window. 

Move the cursor to the newly added routine2 entry in the Breakpoints window. 
Double-click the left mouse button on the entry. The breakpoint is removed from 
the Breakpoints, Functions, and Source windows. 


Stepping Through the Code 

Move the cursor to the “Run” button in the Source window, and single-click the left 
mouse button. The program is “run” until it hits the breakpoint set earlier in this 
example. The source file corresponding to the breakpoint location that stopped 
the program execution is displayed in the Source window. The source line 
corresponding to the current Instruction Pointer address is indicated by the “»” 
next to the line number where the program has stopped. 

Press the “Show IP” button in the Source window. Information relating to the 
current Instruction Pointer is listed in the Main window status and message area. 

Press the “Line step” button in the Source window. The “»” appears on the next 
source line, which is now highlighted. 

Move the cursor to source line 48, over the source line “routine4();” and 
single-click the left mouse button. The BP indicator appears next to the line, and 
the breakpoint entry is entered in the Breakpoints window. 

Press the “Run” button once more, and the program runs to the break just set. The 
“»” appears next to line number 48, which is now highlighted. 
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Move the cursor to the to the “Source” menu bar entry on the Main screen and 
single click the left mouse button. Then, single click the left mouse button on the 
“Callers” option. Figure 2-6 shows the display. 


Callers 



Figure 2-6. Sample Callers Window 

The information contained in the Callers window is essentially a “push down” 
stack that contains information about the current call stack. 

Press the “Line step” button in the Source window. The “»” appears on the next 
source line, which is now highlighted. Notice the program did not step into the 
routine4() function. The Line step command essentially steps over function calls. 

Now press the “Call step” button in the Source window. This command causes the 
debugger to enter the context of the called function. The file containing the 
routine2() function is displayed in the Source window. The first executable source 
line is highlighted, and the “»” indicator shows the source line corresponding to 
the current instruction pointer. The Callers window is also updated to reflect the 
current debugger context. Press the “Line step” button in the Source window 3 
times. The “»” will be next to the source line “routine3():”, line number 11. 

Now press the “Call step” button in the Source window. The file containing the 
routine3() function is displayed in the Source window. The first executable source 
line is highlighted, and the “»” indicator shows the source line corresponding to 
the current instruction pointer. The Callers window is again updated to reflect the 
current debugger context, routine3. 

Single-click on the “routine2” entry in the Callers window. The context is switched 
back to the function that made the call, namely routine2(), with the Source window 
being updated to show the file and line where the function call was made. The 
Callers window is used in this manner to traverse the call stack. 
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Press the “Show IP” button on the Source window. The current IP information is 
again displayed in the message area of the Main window. The Source window is 
also returned to the current context, which is the function listed at the top of the 
Callers window. 

Press the “Ret step” button on the Source window. This returns the debugger 
context to the calling function. Notice that the Callers window is also updated as 
the stack entry is “popped” from the current call stack. 

Press the “Ret step” button again, and the debugger traverses the stack again, 
returning to the original caller in main(). 

Now press the “Restart” button on the Source window. The program is essentially 
reloaded, and the instruction pointer is reset to the entry point of the program. 
Notice the breakpoints that have been saved and the messages that appear in the 
Main window. 

The entry point in this example is in startup code that has no source files 
associated with it. Thus the debugger displays messages that indicate why it is 
unable to display code in the Source window. 

Press the “Run” button. Since the breaks are still set, the program stops again at 
the breakpoint on line 39 in demol .c. 
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Altering and Displaying Variables 


Move the cursor to the to the “Source” menu bar entry on the Main screen and 
single click the left mouse button. Then, single click the left mouse button on the 
“Locals” option. Figure 2-7 shows the display. 



Figure 2-7. Sample Locals Window 


This window lists all of the defined local variables in the current debugger context, 
and their current values. The window contents can be custom tailored in a variety 
of ways. Refer to “Variable Configuration Window” on page 3-83 for a complete 
description of the available options. Only a few will be shown in this example. 

Press the “Var. Config” (Variable Configuration)” button on the Locals window. 
Figure 2-8 shows the window that will be displayed. 

Press the “Address” button in the Display info. area. 

Single-click on the variable “i” shown in the Visible area. This moves the variable 
to the Not Visible area, meaning the variable will no longer be shown. This is used 
to reduce clutter of uninteresting variables and also to reduce the number of 
variable values requiring refresh when the debugger context changes. 
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Figure 2-8. Sample Variable Configuration Window 


Press the “OK” button in the Variable Configuration window. This applies the 
changes and removes the window. Notice variable “i” is no longer shown, and that 
the addresses of all the variables are now displayed. 

Individual variables may also be custom tailored. Single-click on the “show_out” 
variable in the Locals window. Figure 2-9 shows the display. 
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—J_Change Variable 

Local Struct/Union Variable Name: - 
show.out 


i—Read info* — 

—Value Format 

_J Show Address 

Y : .l;*<' P: 

Show Size 

O »*.' Ptr 

Show Type 


□ Use Block Read 


W Use Defaults 

Quinary 

- 1 

Cast 



—Variable detail — 

CK-'-'-U 

OMore detail 

Q’iiqned 

OLess detail 

O Qm»d 

Leave detail 

au ! t 

Enter type (ex* int*, file:struct_a*, etc): 

r 


OK Cancel | Help 


Figure 2-9. Change Display Information 

The “Address” button in the Display info, field is selected because of the previous 
Variable Configuration window update. Press the button again to deselect the 
“Address” button. Press the “OK" button to apply the change and remove the 
window. Notice the Locals window display no longer shows the address of the 
show_out variable. 

Move the cursor again to the show_out variable and double-click the left mouse 
button. Notice that the variable is “expanded” to show another level of detail of the 
structure. Double-click on the show_out variable again to show even more detail. 
Move the cursor down three lines to the “.name:” variable name, and double-click 
on it. Notice that just that variable gets expanded even further. 

Single-click on the “.name:” variable. Notice in the Change Array Variable window 
that the subrange shown can be tailored. Change the “0,2” to “2,6” and then press 
“OK”. Now only array elements 2-6 are shown in the Locals window for the 
“.name:” array. 
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Single-click on the +2 next to the “.count:” variable. Figure 2-10 shows the display. 


Change Variable 

—Local Base Variable Name:— 
show.out.show.in.count 


Read info* — 

Value Format 

□ Show Address 

P :•!-■= « fc'-v 

□ Show Size 

O il”-- *<■' ! : tr 

□ Show Type 

Q ASCII 

□ Use Block Read 

O FIT i I rtrin? 

W Use Befaults 

OBinary 


O Cast 


Q Hexadecimal 

| —Variable detail 

Cl Octal 

d*. > l' J 3: ! 

OSigned 

) Lew de t % 11 

O Unsigned 

Leave detail 

Default 


Change value: 

I 


OK | Cancel J Help 


Figure 2-10. Change Base Variable 

Press the “Hexadecimal” button in the Value format field. Enter 10 in the Change 
value field, and press “OK”. Notice that the display for the “.count:” variable is now 
in hex, and reflects the decimal value 10 just entered. Single-click on the “rlvar:” 
variable, and change the Value format to “Hexadecimal” as well. Press the “OK” 
button to change the variable. 
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Press the “Line step” button in the Source window. Notice no variables are 
updated since “i” was moved to invisible earlier. Press the “Line step” button 
again. Notice that the variable “show_out.show_in.count” got updated in the 
Locals window as the source line was executed. 

The Globals window operates in the same manner as the Locals, but contains 
variables defined as global in the program. 


Debugging at the Assembly Level 

Assembly level debug can be accomplished in several ways. One way is via a 
source disassembly in the Source window. Another is to use an actual memory 
disassembly found in the Assembly Debug window. 

Press the “Delete All” button on the Breakpoints window. Notice that all the 
breakpoints are cleared in both the Source and Breakpoints windows. Single-click 
on the source code of line 47 in the Source window to set a breakpoint. Run to 
that breakpoint by pressing the “Run” button in the Source window. 

Press the “Call step” button in the Source window. Notice that the source file 
associated with the called function, routine5, is shown as “?” in the Source 
window. In addition, some of the buttons have been disabled, and some warning 
messages have been posted in the Main window. Also, no local variable 
information is available. 

This is a result of stepping into a function that was compiled with no debug 
information—a prime example of why it might be desirable to do assembly level 
debug with a source level debugger. Notice also that the warning message 
presents the opportunity to return immediately to the calling function in case the 
Call step issued was inadvertent, or the user decides not to step through the 
assembly code. 

But since you are still reading this, we’ll have to assume you are a hard core user 
and want to move on! Move the cursor back to the Main window to the “Hardware” 
menu bar entry and single-click the left mouse button. Then, single-click on the 
“Asm Debug” option. Figure 2-11 shows the display. 
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Assembly Debug: 1 


J 


Address Data 


Disassembly 



0000A1D8 

0000A1DC 

0000A1E0 

0000A1E4 

0000A1E8 

0000A1EC 

0000A1F0 

0000A1F4 

0000A1F8 

0000A1FC 

0000A200 

0000A204 

0000A208 

0000A20C 

0000A210 

0000A214 


9421FFC0 

90610058 

80820008 

38600005 

90640000 

30210040 

4E800020 

00000000 

00002040 

80000101 

00000000 

0000001C 

0008726F 

7574696E 

65350000 

00000000 


stwu 
stw 
lwz 
addi 
stw 
addic 
blr 

** Unknown 
** Unknown 
lwz 
** Unknown 
** Unknown 
** Unknown 
andis. 
oris 
** Unknown 


Rl,0xFFFFFFC0<Rl> 
R3,0x00000058<R1> 
R4,0x00000008(R2> 
R3,0,0x0005 
R3,0x00000000 <R4) 
R1,R1,0x0040 

opcode (0> ** 
opcode (0> ** 

R0,0x00000101(0) 
opcode <0> ** 
opcode (0> ** 
opcode (0) ** 
R20,Rll,0x696E 
R21,R9,0x0000 
opcode (0) ** 


n 

I 

I 


z\ 


□ 


Run 


Asmstep 


Read 


Close 


Help 


STOPPED 


Step count Set IAR 


00000001 


0000A1D8 


W Track IAR 
□ Show offsets 


Figure 2-11. Sample Assembly Debug Window 


This contains a memory disassembly of a number of instructions, beginning with 
the one corresponding to the current instruction pointer. Press the “Asmstep” 
button in the Assembly Debug window. Notice the current instruction indicator has 
moved to the next assembly instruction. Also notice that the “Return step” button 
on the Source window has been disabled. 

This is the debugger’s way of politely saying that you had your chance to return 
easily per the previous warning message, and you chose not to, so you’re on your 
own getting back! 

This can be done either by pressing the “Asmstep” button until the return is made, 
or by going back to the source line calling the function and setting a break after 
the line and running to it. We'll do the former since this function has only a few 
instructions. 

Press the “Asmstep” button until the return is made to the calling function. The 
Source window is updated to show the source file containing the original call. 
Notice that the current instruction pointer is still pointing to the line number 
containing the call. 
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The source disassembly feature can be used to show why this is the case. Press 
the “Source/Asm” button in the Source Mode area of the Source window. This 
produces a mixed source and disassembly listing in the window. Notice that there 
is more than one assembly instruction associated with each source line. In our 
example, we returned from the function call, but we're still on the same source line 
as the call itself. 

Breakpoints can also be set while in mixed mode. Move the cursor to the “cror 
31,31,31 ” instruction below the routine2() source line and single-click on it. Notice 
that the breakpoint is indicated in the Source, Assembly Debug, and Breakpoints 
windows. 

Press the “Run” button in the Source window. Notice that the current instruction 
pointer is updated at the breakpoint address in both the Source and Assembly 
Debug windows. 

Press the “Source only” button in the Display mode area in the Source window. 
Notice that the break is still shown on the source line corresponding to the 
assembly line on which the breakpoint was set. 

Numerous other screens are also useful when doing assembly level debug. 
Please refer to Table 3-1, “Quick Reference for the RISCWatch Debugger” on 
page 3-2, for a list of the available windows. 
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Chapter 3. Using the RISCWatch Debugger 

RISCWatch is designed to be run in one of several configurations: 

• Normal mode 

The user interacts with the graphical user interface. This is the mode in 
which RISCWatch is usually run. 

• Command file batch mode 

RISCWatch runs via commands contained in an ASCII file. A shell script 
can, for example, invoke RISCWatch several times with several command 
files. The graphical user interface is not available in this mode. See “Run¬ 
ning a Command File” on page 3-133 for more details on how to run RISC¬ 
Watch in this mode. 

• TTY mode (non-PC host only) 

This mode allows RISCWatch to be run on a UNIX (RISC System/6000) 
workstation which does not have a graphical user interface windowing sys¬ 
tem available. This mode provides a command line interface where com¬ 
mands are typed in after a TTY prompt and resulting execution messages 
are printed to the terminal. This mode is invoked by starting RISCWatch with 
the -tty command line option. 

Target types currently supported by RISCWatch are described in “Environment 
Resources” on page 3-5. 


Debugger Facilities 

The RISCWatch Debugger has many facilities that can be used to develop, test, 
and debug your evaluation board code and programs. As you find it necessary to 
perform certain tasks, this section can be used as a quick lookup of the facilities 
that might be used to accomplish those tasks. Table 3-1 below provides a quick 
reference to RISCWatch resources, both in this chapter on general debug 
features and in the next chapter on processor-specific debug features. 
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Table 3-1. Quick Reference for the RISCWatch Debugger 


Task or Resource 

Applicable Sections 

Setting the Environment 

How to initialize the environment resources, 
register definition files, and multi-processor files 

“Environment Resources” on page 3-5 
“Core + ASIC Resources” on page 3-9 
“Multi-Processor Resources” on page 3-28 

Invoking the Debugger 

How to bring up the RISCWatch Main Window 

“Invoking the Debugger” on page 3-33 
“JTAG Ethernet Targets and the RISCWatch 
Processor Probe” on page 3-35 

Main Window Resources 

Overview of menus and windows 

“Main Window Resources” on page 3-38 
“Menus” on page 3-39 
“Command Line Usage” on page 3-42 
“Command History Usage” on page 3-42 
“Message Window” on page 3-43 

Running Your Programs 

How to compile, load, and execute programs 

“Preparing the Program for Debug” on 
page 3-43 

“Loading Files” on page 3-44 
“Loading Boot and Boot Image Files” on 
page 3-46 

“Executing the Program” on page 3-47 
“Following Program Execution Flow” on 
page 3-47 

“Input Line Usage” on page 3-48 
“Scrolling Source Window Contents Using the 
Keyboard” on page 3-54 

Source Level Debugging 

How to use the interface to debug your C 
source code 

“Source Window” on page 3-51 
“Assembly Debug Window” on page 3-54 
“Programs Window” on page 3-58 
“Callers Window” on page 3-60 
“Files Window” on page 3-61 
“Functions Window” on page 3-62 
“Load Memory Window” on page 3-63 

OS Open Debugging 

How to use the interface to display operating 
system information and to control debug 
attachment 

“OS Open Debugging” on page 3-66 
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Table 3-1. Quick Reference for the RISCWatch Debugger 

Task or Resource 

Applicable Sections 

Managing Breakpoints 

How to use the interface and command set to 
set hardware and software breakpoints 

“Managing Breakpoints” on page 3-70 
“Using Software Breakpoints” on page 3-71 
“Using Hardware Breakpoints” on page 3-72 
“Breakpoints Window” on page 3-73 
“Breakpoint Select Window” on page 3-75 
“Trigger/Trace Window (400Series Only)” on 
page 4-7 

“Compound Trigger/Trace Window (401,403 
Series Only)” on page 4-12 

Reading and Writing Program Variables 

How to use the interface to read, modify, and 
write program variables 

“Reading and Writing Program Variables” on 
page 3-77 

“Local Variables Window” on page 3-77 
“Global Variables Window” on page 3-79 
“Inspect Variable Windows” on page 3-81 
“Variable Configuration Window” on page 3-83 
“Change Variable Window” on page 3-85 
“Formatting Examples” on page 3-88 
“Source Variable Command Support” on 
page 3-103 

Reading and Writing Memory 

How to use the interface and command set to 
read, modify, and write processor memory in 
many different formats 

“Reading and Writing Memory” on page 3-104 
“Assembly Debug Window” on page 3-54 
“Memory Coherency Window (JTAG Targets 

Only)” on page 3-105 
“ASCII Memory Window” on page 3-108 
“Custom Memory Window” on page 3-110 
“Cache Windows (JTAG Targets Only)” on 
page 3-113 

“Translation Lookaside Buffer Window (Applica¬ 
ble Processors Only)” on page 4-15 
“Load Memory Window” on page 3-63 
“Save Memory Window” on page 3-114 

Reading and Writing Registers 

How to use the interface and command set to 
read, modify, and write processor registers and 
register fields 

“Reading and Writing Registers” on page 3-116 
“Register Windows” on page 3-117 
“Register Field Windows” on page 3-118 
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Table 3-1. Quick Reference for the RISCWatch Debugger 


Task or Resource 

Applicable Sections 

User-Defined Windows 

How to create and run customized windows 

“User-Defined windows allow a RISCWatch user 
to create windows containing customizable reg¬ 
ister, register field, memory, disassembly, and 
button entries. Using a simple syntax, ASCII 
files are created to define the contents of a 
user-defined window.” on page 3-119 

Command Files 

How to create and run command files which are 
used to perform repetitious tasks and help to 
automate testing 

“Command Files” on page 3-125 
“Command File Programming” on page 3-127 
“Command File Special Expressions” on 
page 3-129 

“Command File Parameters” on page 3-130 
“Command File Pseudo-Variables” on 
page 3-131 

“Running a Command File” on page 3-133 
“Command File Programming Example” on 
page 3-133 

“Running a Command File” on page 3-133 
“Command File Window” on page 3-135 

Processor Resources 

How to use the interface to perform processor 
resets and to read processor status 

“Processor Resources” on page 3-137 
“Processor Reset Window (JTAG Targets Only)” 
on page 3-138 

General Resources 

How to use various program resources 

“Window Layout” on page 3-138 
“Output Window” on page 3-139 
“Window List” on page 3-141 
“Log Files” on page 3-141 
“Logging Control” on page 3-142 
“Logging User Comments” on page 3-142 
“Screen Capture” on page 3-143 
“Calculator Window” on page 3-143 
“Online Help” on page 3-145 

RISCTrace 

Describes using RISCTrace and the trace 
capabilities of 400Series processors 

“Using RISCTrace (400Series JTAG Processor 
Probe Only)” on page 4-2 


It may prove helpful to glance through each of the sections listed in Table 3-1 to 
gain an overall picture of the available facilities that RISCWatch offers. Such an 
understanding can help you avoid doing something “the hard way.” 


3-4 


RISCWatch Debugger User's Guide 



Environment Resources 

RISCWatch employs an environment resources file to specify or configure various 
resources. This file, rwppc.env, is designed to allow the RISCWatch user to tailor 
program operation to meet specific operating preferences. This file should be 
examined and changed where necessary, before RISCWatch is run to ensure that 
the environment will conform to your debugging needs. 

What follows is a list of the environment resources that can be used in the 
rwppc.env file and their functionality: 

Environment variable Description 

Specifies the target processor name for non-MPS 
RISCWatch debug sessions (required). See the 
README file provided with RISCWatch for a list of valid 
processor names. 

Specifies the revision number of the target processor. 
This field is required when debugging a 6xx/7xx 
processor in which RISCWatch supports more than one 
revision number. For example, if debugging a 603e REV 
3 processor, ”REV = 3” must be designated. 

jtag_par, jtag_par1, jtag_par2, jtag_par3, jtag_eth, 
rom_mon, osopen (one required) 

Refer to the README file which came with RISCWatch 
for information concerning host and target requirements 
for proper RISCWatch operation. 

Each target type is described below. 

JTAG parallel port target. RISCWatch is connected to the 
JTAG port, on the PowerPC 400Series target system, 
through a RISCWatch parallel port adapter. The suffix 
(1,2, or 3) is used to specify a specific parallel port 
address on PC hosts (1 uses 0x3BC, 2 uses 0x378, 3 
uses 0x0278). The optional suffix should only be used if 
the default address (designated by jtag_par) does not 
determine the correct address to use 

jtag_eth JTAG Ethernet target. RISCWatch is connected via 

Ethernet to a RISCWatch processor probe. The JTAG 
connector of the processor probe is then connected to 
the JTAG port on the PowerPC 400Series or PowerPC 
6xx/7xx target system. 


PROC 


REV 


TARGET TYPE 


jtag_par<1,2,3> 
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rom_mon 

os_open 

TARGET_NAME 

RWPPC_DIR 

SEARCH_PATH 

LOG_FILE_DIR 

STACK_FRAMES 

LAYOUT 


APPLPROG_NAME 
FONT SIZE 


COLOR_CTRL_BG 

COLOR_CTRL_FG 

COLOR_TEXT_BG 

COLOR_TEXT_FG 

COLOR_WIN_BG 

COLOR WIN FG 


ROM monitor target. RISCWatch is connected via 
Ethernet or SLIP to a PowerPC target system running 
the IBM ROM Monitor for PowerPC in debug mode. 

OS Open target. RISCWatch is connected via Ethernet 
or SLIP to a PowerPC target system running IBM’s OS 
Open real-time operating system. 

Name of target found in TCP/IP services file (required 
for JTAG Ethernet, OS Open and ROM Monitor targets) 
TCP/IP dotted address may also be used. 

A fully qualified path name to the directory in which the 
RISCWatch executable and support files reside. This is 
required for all targets. 

Path names used for source/object/command file 
search, delimited by colons (:); for a PC host, the 
delimiter is a semicolon instead of a colon, (if not 
specified, default = current directory) 

A fully qualified path name to the directory of where 
RISCWatch is to maintain all log files. 

Indicates the number of stack frames to show on the 
Callers Window. If not designated, the default setting is 
twelve. 

Save/load window layout when ending/beginning 
session. “SAVE” will save the layout on exit. “LOAD” will 
load the layout when starting. “LOADSAVE” (or omitting 
the variable altogether) will do both. “NONE” will do 
neither. 

Allows renaming of applprog executable (OS Open 
target only) 

Specifies the font size to use in the main window for the 
text in the command history and message windows. 
This size should be one of 8, 10, 12 or 14. 

Specifies color for background control areas 
(non-MPS) 

Specifies color for foreground control areas (non-MPS) 
Specifies color for background text areas (non-MPS) 
Specifies color for foreground text areas (non-MPS) 

Specifies color for background window areas 
(non-MPS) 

Specifies color for foreground window areas (non-MPS) 
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MPS_FILE 

PRD_FILE 

REG_FILE 

STARTUP_FILE 

PROBE_FLASH 

AUTO 

NO 

YES 

TRACE ENABLE 


Specifies file containing multiprocessor support 
configuration and options. See “Multi-Processor 
Resources” on page 3-28 

Specifies a single file containing user defined registers, 
register fields and chips. See “Core + ASIC Resources” 
on page 3-9 for additional information 

Specifies a file containing user defined register and 
register fields and has been replaced by the PRD_FILE 
environment variable. See “Core + ASIC Resources” on 
page 3-9 

Specifies a command file which will be run each time 
RISCWatch is started. See“Command Files” on 
page 3-125. 

Specifies the firmware loading sequence for JTAG 
ethernet targets. 

When RISCWatch is first invoked, a time stamp 
comparison is made between the preloaded Processor 
Probe firmware and the firmware files (drivers) provided 
with RISCWatch. If the time stamps do not match, the 
RISCWatch firmware files are loaded. This is the default 
operation of RISCWatch if PROBE_FLASH is not 
designated in the environment file. 

The Processor Probe will not be loaded with the 
RISCWatch firmware files. Any firmware file time stamp 
checks are ignored. Warning: The user assumes 
responsibility for guaranteeing that the firmware loaded 
on the Processor Probe is compatible with the target 
processor and the version of RISCWatch being used. 

The Processor Probe will be loaded with the firmware 
files provided with RISCWatch. Any firmware file time 
stamp checks are ignored. RISCWatch initialization time 
will be extended to load both the generic and processor 
specific driver files. 

Specifies one or more RISCWatch commands to be 
executed prior to starting trace. If more than one 
command is needed, each additional command must be 
preceded by a semicolon (i.e. TRACE_ENABLE = write 
0x0 22;set gpio = 15). This optional variable is only 
applicable to PowerPC 400Series Core+ASIC JTAG 
targets, where unique register or memory initialization 
may be required to enable the trace feature. The 
designated commands will be executed during the 
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processing of the trace run command, which can be 
called from the RISCWatch Trigger or Compound Trigger 
windows. Please note that the exec command is not a 
valid TRACE _ENABLE designation. 

TRACE_DISABLE Specifies one or more RISCWatch commands to be 

executed immediately following the first stop request after 
a trace run. If more than one command is needed, each 
additional command must be preceded by a semicolon 
(i.e. TRACE_DISABLE = write 0x0 22;set gpio = 
15;memacc clear). This optional variable is only 
applicable to PowerPC 400Series Core+ASIC JTAG 
targets, where unique register or memory initialization 
may be required to disable the trace feature. The 
designated commands will be executed during the 
processing of the trace run command, which can be 
called from the RISCWatch Trigger or Compound Trigger 
windows. Please note that the exec command is not a 
valid TRACE _DISABLE designation. 

IR_SEG0 Specifies a binary sequence to be added to each JTAG 

SCANJR command. This variable is only applicable to 
PowerPC 400Series Core+ASIC JTAG targets. The 
binary sequence indicates the number of bits added to 
the SCANJR chain as well as the value needed to 
communicate with the core processor. For example, 
‘IRJ3EG0 = 100’ indicates the value of three additional 
bits that are connected to the end (TDO) of the SCANJR 
chain. The user assumes responsibility for identifying the 
correct binary sequence. 

File syntax consists of placing the resource name on a new line, and then 
following it with one or more spaces, an equal sign, one or more spaces and then 
specifying the resource value. 

For example: 

RWPPCJDIR = /usr/rwppc 

To enhance readability of this file, comment and blank lines are allowed. A 
comment can only start in the first column and does so by beginning with the # 
character. 

Every time RISCWatch is started, it attempts to locate the environment resources 
file using the following rules: 

1. Check to see if it is in the current directory; if so, use it 

2. If a relative or absolute path is given for the executable, see if the environ¬ 
ment file is in the same directory as the executable. If it is, use it. 
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3. Check to see if it is in a directory specified by the environment variable 
PATH; if so, use it, else 

4. Print an error message and terminate RISCWatch. 


Core + ASIC Resources 

With the introduction of the IBM PowerPC 401 Core and a growing library of on 
chip peripherals, IBM offers high-performance custom processors. Using a single 
PowerPC core, hundreds of unique chips can be developed to satisfy specific 
customer needs. 

Many of the basic functions performed by a debugger (line stepping, memory 
display, etc.) depend on both PowerPC core and peripheral resources. 

RISCWatch allows users to define both the register organization and the memory 
configuration of their Core+ASIC environment. The following user interfaces are 
provided to accomplish this task: 

1. Processor Definition File: used to define the processor and ASIC 
resources that RISCWatch will need to access 

2. memacc Command: used to define the correct access size and 
read/write restrictions of any memory access initiated by RISCWatch 

3. Window Descriptor File: used to create User-Defined RISCWatch 
windows which can be used to display specified registers, register fields, 
or memory regions. 

The following sections provide additional details about these Core+ASIC 
interfaces. Please read all sections to get a complete understanding of the 
flexibility RISCWatch provides for custom chip designs. 

Processors, Cores and Chip Resources 

When RISCWatch is first started, the Processor Resource Definition (PRD) file is 
read to determine the debug environment. The PROC environment variable, 
designated in the environment file (rwppc.env), is used as an index into the PRD 
file to completely define the unique resources (processor, cores, registers, TLBs, 
caches, etc.) of the specified target. The default PRD file is updated with each 
new version of RISCWatch to contain the latest definitions for all standard 
PowerPC chips. 

With the increasing popularity of Core + ASIC designs, a flexible debug solution is 
needed to allow debugging on non-standard, customer specific PowerPC parts. 
RISCWatch makes use of Processor Configuration Files (PCF) to provide this 
solution. These ASCII text formatted files allow users to define the processor, 
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core, and chip resources (registers, cache, memory, etc.) needed to uniquely 
define a custom design. 

Users working on standard PowerPC parts (403GCX, 603e, etc.) can use the 
resources defined in the default RISCWatch PRD file (rwppc.prd) for their 
debugging sessions. This file is loaded by default and is totally transparent to the 
end user. If a custom Core + ASIC solution is being used, or additional register 
definitions are needed, a new PRD file will need to be created by compiling one or 
more customer supplied Processor Configuration Files. 

Processor Configuration File (PCF) 

Processor Configuration Files (PCF), introduced with RISCWatch version 4.3, are 
created by the user prior to starting RISCWatch. These files contain the resource 
definitions required to uniquely define the target debug environment. This new file 
format, with its enhanced support for Indirectly Mapped Registers, replaces the 
Register Definition File format of previous releases (see Appendix B, "Register 
Definition File (Outdated)"). 

Once created, the PCF file must be compiled into a loadable form. The user must 
invoke the RISCWatch PCF compiler program (rwpcfc) with the PCF file name 
designated as an input argument. If no errors are detected, a new Processor 
Resource Definition (PRD) file is created. This new file will have the same PCF 
base file name, with a file extension of ".prd". 

The RISCWatch PRD_FILE environment variable is used to identify the name of 
the customized PRD file. Upon initial program startup, RISCWatch will read the 
designated PRD file to determine the unique target debug environment. Only one 
PRD file can be designated and it is located using the following rules: 

• If the file name is qualified (directory path indicated), the file search is 
performed using the specified directory only. 

• If the name is not qualified, the file search is performed using the directory 
paths designated with the RISCWatch SEARCH_PATH environment 
variable. If not found, the current directory is searched. 

File Management 

The Processor Configuration File (PCF) is an ASCII file that can be created with 
any text editor. Once defined, it must be compiled by the rwpcfc compiler 
program. Typically, a PCF file contains definitions for a unique ASIC macro. 

The easiest approach is to simply put all definitions into a single PCF file so all the 
necessary information can be easily located and edited as needed. Other times it 
might make more sense to create multiple files, each containing the necessary 
details for a separate macro. It will be up to each user to determine which method 
works best for them. 
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If just one PCF file is created, it can be simply compiled on its own. If the multiple 
PCF file approach is used, there needs to be one “master” PCF which is used to 
gather the other low-level PCF files into one, coherent entity. When the low-level 
PCF files are compiled, they need to use the -refer flag which tells the compiler 
that they will later be included, or referred to (using REFER), by another file. 

Regardless of how deeply these low-level files are nested, if they will be included 
by another PCF file, they need to be compiled with the -refer flag. Once it is time 
to compile the highest level “master” PCF file, the -refer flag is NOT used since it 
represents the highest level of user compilation. 

Successful compilation of the highest level “master” PCF file will result in a valid 
PRD file whose name can then be specified in the RISCWatch environment file 
with the PRD_FILE variable. 

RISCWatch comes with a default PRD file (rwppc.prd) which is automatically 
loaded if no PRD_FILE environment variable is specified. 

File Syntax 

The general syntax rules for the PCF file are as follows: 

1. The "#" character denotes the start of a comment. All text following the 
"#" character on a given line will be ignored. 

2. Blank lines are allowed and will be ignored. 

3. Any error detected while compiling the PCF will generate error messages 
and terminate execution of the compiler. 

4. Hex values are preceded by ‘Ox’, such as 0x12AB0423. 

5. Implied Hex values are not preceded by ‘Ox’, such as ABCD1245. 

The following sections define the complete list of PCF definitions and their valid 
line entries. 

REFER Definitions 

The REFER definition indicates that the current PCF file will use resources 
defined in another PCF file. This functionality allows a PCF file to refer to 
resources defined in another. The rwpcfc compiler does not allow a reference 
before a definition. For this reason, REFER definitions should appear at the very 
top of the PCF file so that when resources are referenced later in the current PCF 
file, the compiler will already be aware of them. 

Each REFER definition must adhere to the following syntax: 

REFER filename.prd 
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Where: 

• filename.prd is the name of the PRD file which is the result of successfully 
compiling its associated PCF file. 

Note: If a resource is referenced before it has been defined, an error message will 
be generated and the compile will be aborted. Place the REFER definitions near 
the top of the file to define all resources before they are referenced further down in 
the file. 

MACRO Definitions 

The MACRO definition is the basic building block of the PCF file and allows for a 
high degree of modularity and reusability. By carefully defining PCF file MACROS 
along logical or functional divisions, references can be made to them by countless 
other definitions. Such abilities may not seem important if only one chip is being 
defined but it becomes crucial if the same or similar resources are used in multiple 
ASIC designs. 

Each MACRO definition must adhere to the following syntax: 

DEFINE MACRO macro_name 
macro_def 
END 

Where: 

• macro_name is the unique name being assigned to this MACRO and is the 
name by which other definitions will reference it. This name can only contain 
alpha-numeric and underscore (_) characters. 

Note: the prefix “PPC_” has been reserved for debugger use. Therefore 
no macro_name may begin with “PPC_” 

• macro_def represents one or more MACRO definitions, each of which defines 
one resource. The resources which can be defined in a MACRO are fields 
(FIELD definition), registers (REG definition) and register fields (REGFLD 
definition). See below for information about these definitions. 

Note: If a resource is referenced before it has been defined, an error message will 
be generated and the compile will be aborted. 

CHIP Definitions 

There are two forms of CHIP definitions. One is used to define a chip based on an 
existing RISCWatch defined core (DEFINE CHIP) while the other is used to add 
resources to an existing RISCWatch defined chip (APPEND CHIP). 

A DEFINE CHIP definition must adhere to the following syntax: 

DEFINE CHIP chip_name 
dc_def 
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END 


Where: 


• chip_name is the unique name being assigned to this CHIP and is the 
name used to set the PROC environment variable. 

• dc_def represents one or more DEFINE CHIP entries, each of which 
defines or includes one resource. The resources which can be defined are 
names (NAME definition), PVRs (PVR definition) and firmware revisions 
(REV definition). The resources which can be included are macros and a 
single core (INCLUDE definition). See below for information about these 
definitions. 

The following restrictions apply to a DEFINE CHIP definition 

1 . There must be one and only one INCLUDE CORE definition 

2. There may be zero or more INCLUDE MACRO definitions 

3. There may be zero or more DEFINE NAME definitions 

4. There must be at least one DEFINE PVR definition 

An APPEND CHIP definition must adhere to the following syntax: 

APPEND CHIP chip_name 
ac_def 

END 

Where: 


• chip_name is the unique name being assigned to this CHIP and is the 
name used to set the PROC environment variable. 

• ac_def represents one or more APPEND CHIP entries, each of which 
defines or includes one resource. The resources which can be defined are 
field (FIELD definition), name (NAME definition), register (REG definition), 
register field (REGFLD definition), register alias (REGALIAS definition), 
PVRs (PVR definition) and firmware revisions (REV definition). The 
resources which can be included are macros and a single chip (INCLUDE 
CHIP definition). See below for information about these definitions. 

The following restrictions apply to an APPEND CHIP definition 

1. Any included MACROS may only contain REG, REGFLD and REGALIAS 
entries 

2. There may be zero or more REG definitions. 

3. There may be zero or more REGFLD definitions. 

4. There may be zero or more REGALIAS definitions. 
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5. There must be one INCLUDE CHIP definition. 

Note: If a resource is referenced before it has been defined, an error message will 
be generated and the compile will be aborted. 

For the list of RISCWatch defined CHIPs and COREs which are available for use, 
see the on-line FAQ available via the program Help pulldown, or visit the 
RISCWatch Support Center web page. 

The following sections define the complete list of valid line entries for the DEFINE 
MACRO, DEFINE CHIP and APPEND CHIP definitions. 

INCLUDE Definitions 

There are three forms of INCLUDE definitions which allow the inclusion of a 
previously defined CHIP, CORE, or MACRO definition. 

An INCLUDE CHIP definition must adhere to the following syntax: 

INCLUDE CHIP chip_name 
Where: 


• chip_name is the unique name of the chip being included. These chip 
names are defined by IBM and are representative of the parts contained in 
the PowerPC processor library. Examples of valid chip names include 
PPC_403GCX, PPC_603EV, PPC_740, PPC_750, and PPC_401C2. 

An INCLUDE CORE definition must adhere to the following syntax: 

INCLUDE CORE core_name 
Where: 


• core_name is the unique name of the core being included. These core 
names are defined by IBM and are representative of the parts contained in 
the PowerPC ASIC library. Examples of valid cores names include 
PPC_401 M1_CORE, PPC_401 B2_CORE, and PPC_401C2_CORE. 

An INCLUDE MACRO definition must adhere to the following syntax: 

INCLUDE MACRO macro_name [offsef\ 

Where: 


• macro_name is the unique name of a previously defined MACRO 
definition. 

• offset is an optional address offset which is used for relocatable register 
MACROS. The offset is added or subtracted (depending on the specified 
sign) to each register definition contained in the referenced MACRO. This 
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allows a "base" definition to be defined once and then relocated anywhere 
in the memory address space. 

Note: If a resource is referenced before it has been defined, an error message will 
be generated and the compile will be aborted. 

For the list of RISCWatch defined CHIP, CORE and MACRO names available for 
use on the INCLUDE directive, see the online FAQ available via the program Help 
pulldown, or visit the RISCWatch Support Center web page. 

EXEC Definitions 

An EXEC definition is used to associate a name with an ordered sequence of 
RISCWatch commands which will be executed whenever the register it is 
referenced from is read or written (See REXEC and WEXEC keywords listed 
under REG Definitions). Each EXEC definition must adhere to the following 
syntax: 

DEFINE EXEC exec_name 
command 
ENDEXEC 

Where: 


• exec_name is the unique name being assigned to this EXEC and is the 
name used by REG definitions that reference it. This name can only 
contain alpha-numeric and underscore (_) characters. 

• command is a list of one or more RISCWatch commands which will be 
executed in the order in which they are listed. There can only be one 
command specified per line. Parameters may be passed into the EXEC by 
using the PARMS command (see “Command File Parameters” listed under 
“Command Files”). 

The EXEC definition is basically a mini-command file (see “Command Files”) 
which can be executed whenever customized registers are read from or written to. 
Such functionality provides for a great deal of power but it must be used 
responsibly. Care must be taken to avoid “dangerous” operations. If any other 
processor resources are manipulated while the EXEC runs, it is usually wise to 
back up data values before the EXEC starts executing and then restore these 
values just before leaving the EXEC. 

To facilitate the transfer of data values into and out of these customized register 
EXEC definitions, RISCWatch provides the $INPUT and $RETURN 
pseudo-variables. Whenever the REG command is used to write a value to a 
register which uses an EXEC definition, the commands inside the EXEC can 
reference $INPUT to obtain the data value to be written. Likewise, while using the 
REG command to read an EXEC definition register, $RETURN can be set to the 
value read so that it may be referenced once the EXEC returns. 
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See the “PCF Example” section which follows for more details. 

FIELD Definitions 

A FIELD definition is used to associate a name with defined logical bit groupings 
so that it may be referenced later by another resource. Each FIELD definition 
must adhere to the following syntax: 

DEFINE FIELD fleld_name {fleld_def\ 

Where: 


• field_name is the unique name being assigned to this FIELD and is the 
name used by other definitions to reference it. This name can only contain 
alpha-numeric and underscore (_) characters. 

• field_def defines one or more bit fields. Each bit field must adhere to the 
following syntax: 

name start length 

Where: 

• name is the unique name being assigned to this bit field and is the 
name used to reference it. This name can only contain 
alpha-numeric and underscore (_) characters. 

• start is the decimal physical starting bit (MSB=0) of this bit field 

• length is the decimal length of this bit field in bits 

NAME Definitions 

The NAME definition is used to define a name to a given chip. Many chips are 
known by both a marketing name (i.e. 740), and a "pet" name (i.e. Arthur). 

This definition allows any number of "pet" names to be defined and is intended to 
give a unique code name for a given chip definition. Once defined, the "pet" name 
can be used when specifying the value of the PROC variable in the RISCWatch 
environment file. 

A NAME definition must adhere to the following syntax: 

DEFINE NAME user_name 
Where: 


• user_name is the unique name being assigned. This name can only 
contain alpha-numeric and underscore (_) characters. 

PVR Definitions 

The PVR definition is used to define the value of the PVR for the given chip. When 
RISCWatch is started, the PROC environment variable, along with the PRD file, 
are used to define the resources of the target system. Once communication with 
the chip has been established, the PVR register will be read and compared to the 
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PVR definition value. A miscompare of these values will result in a warning or 
error message to the user. Multiple PVR definitions are allowed to help account for 
changes in the PVR due to multiple revisions of the same ASIC. 

A PVR definition must adhere to the following syntax: 

DEFINE PVR pvr_vatue 
Where: 


• pvr_value is the processor’s unique PVR value and is an implied 
hexadecimal number (ex. DEFINE PVR 40ABCD04). 

REG Definitions 

A REG definition is used to define an instance of a physical register. Each REG 
definition must adhere to the following syntax: 

DEFINE REG reg_class reg_name 

#\address\addr_reg addr_val data_reg 
bit_width R|W|RW [access] [VOLATILE] [display] 

[REXEC exec_name[{parm_list\]] 

[WEXEC exec_name[{parm_lisf\]] 

Where: 


• reg_class is the class of register being defined; DCR, IMR, SPR or MMIO 

• reg_name is the unique name being assigned to this REG and is the name 
by which other definitions will reference it. This name can only contain 
alpha-numeric and underscore (_) characters. 

Note: registers being defined because they are part of an ASIC 
macro should use a common naming prefix so that they can be 
grouped together by RISCWatch. 

The naming convention RISCWatch supports for ASIC register 
prefixes is to use a few letters as an acronym for the macro, followed 
by a number (usually starting with 0) and ending with an underscore 
(_). This prefix is then added to the beginning of each register 
contained in that macro. 

By following this convention, RISCWatch is able to detect the prefix 
and group the registers accordingly. This allows RISCWatch to 
create an ASICs entry in the Hardware | Register pulldown listing all 
the prefixes it detected during initialization. Selecting one of these 
prefixes then creates a Register window containing all registers with 
this prefix thereby grouping them together to represent the 
associated macro. 

For example, if a PLB bus macro were being added, all registers 
defined for use with the PLB could be prefixed with ‘PLB0_’. 

RISCWatch could then detect this common prefix and the Hardware | 
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Register | ASICs pulldown would list ‘PLBO’. Selecting this entry 
would bring up a Register window with all the PLBO prefixed registers 
in it. 


• # is the hex number for a DCR or SPR register. 

• address is the hex address for an MMIO register. 

• addr_reg is the name of the address register for an Indirectly Mapped 
Register (IMR). 

• addr_val is the value to be written to addr_reg to access an IMR register’s 
contents. 

• data_reg is the name of the data register for an IMR register. 

• bit_width is the decimal width of this register in bits. 

• R|W|RW defines the register’s access; read-only (R), write-only (W) or 
read-write (RW). 

• access is an optional parameter for MMIO registers which is used on JTAG 
ethernet and JTAG parallel port RISCWatch targets. It is a decimal number 
which indicates the access size, in bits, RISCWatch must use when 
reading or writing this memory location. The access size should be 8,16 or 
32, with each multiple identifying a unique PowerPC load/store instruction 
to use. For example, an access size of "16" instructs RISCWatch to read 
the register by executing the "load halfword" PowerPC instruction. 
Specifying an access size will override any access size settings made with 
the memacc command. If no access size is specified, RISCWatch will use 
the access size defined for the memory region. See memacc on page 
5-81 for information about how to set up a unique memory region access 
size. 

• VOLATILE is an optional keyword which indicates this register will change 
its value after a read operation is performed. It must be entered in 
uppercase. RISCWatch users must issue an explicit read to display the 
contents of a volatile register. This keeps RISCWatch from asynchronously 
reading the register thus avoiding changes to it. Having the auto-update 
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mode enabled on a window containing these registers will not cause them 
to be read during the update. 

• display is an optional keyword which indicates the default display format for 
floating point registers; HEX or SCI 

• REXEC is an optional keyword which indicates that a previously defined 
EXEC entry is to be run to read the value of this register. 

• WEXEC is an optional keyword which indicates that a previously defined 
EXEC entry is to be run to write a value to this register. 

• exec_name is the name of a previously defined EXEC entry which is to be 
run. 

• parm list is an optional list of one or more parameters whose values are to 
be passed to the specified EXEC entry. 

Note: If a resource is referenced before it has been defined, an error message will 
be generated and the compile will be aborted. 

REGALIAS Definitions 

A REGALIAS definition is used to refer to a previously defined register by another 
name. 

A REGALIAS definition must adhere to the following syntax: 

DEFINE REGALIAS new_reg = exist_reg 
Where: 


• new_reg is the new register alias name. 

• exist_reg is the name of the previously defined register. 

Note: If a resource is referenced before it has been defined, an error message will 
be generated and the compile will be aborted. 

REGFLD Definitions 

A REGFLD definition is used to define a register field. Each REGFLD definition 
must adhere to the following syntax: 

DEFINE REGFLD register field_name\{field_def\ 

Where: 

• register is the name of a previously defined register. 

• fieid_name is the name of a previously defined FIELD entry. 

• field_def defines one or more bit fields. Each bit field must adhere to the 
following syntax: 

name start length 

Where: 


Using the RISCWatch Debugger 


3-19 



• name is the unique name being assigned to this bit field and is the 
name by which it will be referenced. This name can only contain 
alpha-numeric and underscore (_) characters. 

• start is the decimal physical starting bit (MSB=0) of this bit field. 

• length is the decimal length of this bit field in bits. 

Note: If a resource is referenced before it has been defined, an error message will 
be generated and the compile will be aborted. 

REV Definitions 

The REV definition is used to indicate to RISCWatch which Processor Probe 
firmware files are to be used with a specific definition of a chip/core. For 
chips/cores with multiple revisions, multiple REV definitions may be used to define 
a unique set of files for each, if necessary. 

A REV definition must adhere to the following syntax: 

DEFINE REV n driver generics 

Where: 


• n is the processor revision number. 0 should be used for all PowerPC 400 
family cores/chips. 

• driver is the name of the Processor Probe driver filename to be used for 
this revision. Such names usually start with "E34" and have a ".X" 
extension. 

• generics is the name of the Processor Probe generics filename to be used 
for this revision. Such names usually start with "E34" and have a ".X" 
extension. 


PCF Compiling 

Once a PCF file has been created, it must be compiled by rwpcfc to verify that the 
file syntax is correct and that all definitions are complete. If so, the file is turned 
into a format which can be loaded by RISCWatch at run time. 

The compiler program, rwpcfc, was installed in the same directory as the main 
RISCWatch executable. This is also where the default RISCWatch PRD file is 
located. This PRD file contains a number of predefined processors, cores and 
other resources that may need to be referenced. 

To run the compiler, use the following syntax: 

rwpcfc [-log] [-refer] filename.pcf 

Where: 
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• -log is an optional flag. If present, all messages which are usually printed 
to the screen are directed to the rwpcfc log file (rwpcfc.log). 

• -refer is an optional flag. It must be specified when compiling a file which 
will be REFERred by another file (see the REFER definition above). In 
other words, if file A.pcf has a "REFER B.prd" line in it, file B.pcf must have 
been compiled with the -refer flag, since it is being REFERred to. If only 
one PCF file is being defined and compiled, this option will not be used. 

• filename.pcf is the name of the PCF file that is to be compiled. At this time, 
the compiler is a DOS-based tool so Windows 95/98 long filenames are 
not supported. 

If any errors are detected, an appropriate error message will be printed to the 
screen or log file. These should be used to correct the source of the error 
message(s) prior to attempting a recompile. 

Successful compilation will result in a valid PRD file whose name can then be 
specified in the RISCWatch environment file with the PRD_FILE variable. When 
RISCWatch is started, this variable will be used to load the appropriate resource 
information uniquely defined by the processor/core designated by the PROC 
environment variable value. 

PCF Example 

The following examples are provided to acquaint users with some of the more 
common coding of the PCF file. 

In this example, a few simple memory mapped registers are added to an existing 
chip (a function previously accomplished with the Register Definition File). In 
addition, register fields have been defined for MMIO_2 and MMIO_3: 

APPEND CHIP MY_403GB 
INCLUDE CHIP PPC_403GB 

DEFINE REG MMIO MMIO_1 OxAOOO 32 RW 
DEFINE REG MMIO MMIO_2 0xA004 32 RW 8 
DEFINE REG MMIO MMIO_3 0xA008 32 RW VOLATILE 
DEFINE REG MMIO MMIO_4 OxAOOC 32 RW 8 VOLATILE 

DEFINE REGFLD MMIO_2 { RES 0 16 

AVRL16 8 
AVRR24 8} 

DEFINE REGFLD MMIO_3 { RES 0 16 

AVRL16 8 
AVRR24 8} 

END 
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Once compiled, this would result in a custom PRD file which would be set using 
the PRD_FILE environment variable while the defined chip, MY_403GB, would be 
set using the PROC environment variable. 

In the next example, a MACRO will be used to accomplish the same results as the 
previous example. In addition, macro IMR_REGS is defined to demonstrate how 
to define IMR registers. Note the use of DEFINE FIELD for registers that share the 
same register field designations: 

DEFINE MACRO MMIO_REGS 

DEFINE REG MMIO MMIO_1 OxAOOO 32 RW 
DEFINE REG MMIO MMIO_2 0xA004 32 RW 8 
DEFINE REG MMIO MMIO_3 0xA008 32 RW VOLATILE 
DEFINE REG MMIO MMIO_4 OxAOOC 32 RW 8 VOLATILE 

DEFINE FIELD MMIO_FIELD1 { RES 0 16 

AVRL 16 8 
AVRR 24 8 } 

DEFINE REGFLD MMIO_2 MMIO_FIELD1 
DEFINE REGFLD MMIO_3 MMIO_FIELD1 
END 

DEFINE MACRO IMR_REGS 

DEFINE REG DOR T0_ADDR 0x0180 32 RW 
DEFINE REG DOR T0_DATA 0x0181 32 RW 

DEFINE REG IMR T0_REG1 T0_ADDR 0x00000001 T0_DATA 32 RW 
DEFINE REG IMR T0_REG2 T0_ADDR 0x00000002 T0_DATA 32 RW 
DEFINE REG IMR T0_REG3 T0_ADDR 0x00000003 T0_DATA 32 RW 
END 

APPEND CHIP MY_403GB 
INCLUDE CHIP PPC_403GB 
INCLUDE MACRO MMIO_REGS 
INCLUDE MACRO IMR_REGS 
END 

In the next example, a MACRO will be used to define a base set of registers which 
can be located anywhere within the chip’s address space. Using the offset feature 
of the INCLUDE MACRO statement, this set of registers can be used in two 
different processors in two different memory locations: 

DEFINE MACRO BASE REGS 

DEFINE REG MMIO BASE_1 0x0 32 RW 
DEFINE REG MMIO BASE_2 0x4 32 RW 
DEFINE REG MMIO BASE_3 0x8 32 RW 
DEFINE REG MMIO BASE 4 OxC 32 RW 
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END 


APPEND CHIP MY_A1 

INCLUDE CHIP PPC_401 A1 
INCLUDE MACRO BASEREGS OxAOOOOOOO 
END 

APPEND CHIP MY_B2 

INCLUDE CHIP PPC_401 B2 
INCLUDE MACRO BASE REGS OxFFFOOOOO 
END 

In the next example, a MACRO will be used to define a customized register which 
uses two DEFINE EXEC definitions to create read and write “routines” which can 
then be used to manipulate the contents of this specialized register: 

DEFINE MACRO CUST_REG 
DEFINE EXEC cust_read 

PARMS {stuff_instr} 

STUFF stuffjnstr 
SET $RETURN = 0x00E80024 
ENDEXEC 

DEFINE EXEC cust_write 
PARMS {stuffjnstr} 

WRITE 0x00E80024 $INPUT 
STUFF stuffjnstr 
ENDEXEC 

DEFINE REG DCR APU1 OxFFFF 64 RW 
REXEC cust_read{0x90A10024} 

WEXEC cust_write{0x80A10024} 

END 

MEMACC Command 

When a memory read or write operation is requested, RISCWatch must first 
determine if the request is valid and then determine the proper way to proceed 
with the request. Performing a read to an invalid memory address, or issuing a 
store word instruction to a memory region configured for half word access, could 
result in unwanted machine checks, data corruption, or system hangs. 

When RISCWatch is first started, the target processor name (designated with the 
PROC environment variable) is used to define the type of memory address 
validation to perform. RISCWatch internal address validation can be summarized 
as follows: 
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• On 403GA and GB processor targets, RISCWatch will read the bank 
registers to determine valid address regions and read/write access 
restrictions. Four byte word access is assumed valid for any read or write 
operation. Access type defaults to instruction and data. 

• On 403GC and GCX processor targets, RISCWatch will default to the 
operations defined for the 403GA if translation is off. If translation is on, the 
TLB is read to determine valid address regions and access restrictions. 
Four byte word access is assumed valid for all read/write operations. 
Access type is determined by the instruction and data translation bits 
defined in the machine state register (MSR). Since OS Open performs its 
own address validation when translation is on, RISCWatch assumes all 
addresses are valid for OS Open targets. 

• On 405GP processor targets, RISCWatch will read EBC and SDRAM 
registers to determine address regions and read/write access restrictions 
when address translation is off. If translation is on, the TLB is read to 
determine valid address regions and access restrictions. Four byte word 
access is assumed valid for all read/write operations. Access type is 
determined by the instruction and data translation bits defined in the 
machine state register (MSR). Since OS Open performs its own address 
validation when translation is on, RISCWatch assumes all addresses are 
valid for OS Open targets. 

• On 6xx and 7xx targets, all addresses are assumed valid for both read and 
write access. Access size defaults to 8 bytes. Access type defaults to 
instruction and data. 

• On Core+ASIC processors, all addresses are assumed valid for both read 
and write accesses when address translation is off. Access size defaults to 
4 bytes. Access type defaults to instruction and data. If the MMU is 
enabled, addresses are checked against the current TLB entries. 

Note: For ROM Monitor and OS Open targets, access size is governed by the 

monitor code running on the target processor. 

Obviously, the internal address validation may not be adequate for all users. In an 
effort to provide additional memory access protection, RISCWatch provides the 
memacc command which allows a user to define the unique memory 
configuration associated with a processor target. 

Use of MEMACC ADD 

Users can override any RISCWatch internal address validation checks by 
executing the memacc add command. The command syntax is defined as follows 

memacc add beg_addr end_addr [access [size [type]]] 

Where: 
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• add is a keyword on the memacc command indicating that a new entry is 
to be added to the list of user defined address regions. 

• beg_addr indicates the beginning address of target memory being defined 
with this command. The address can be designated in hex (leading “Ox” or 
“OX”), octal (leading 0), or decimal. 

• end_addr indicates the last address of target memory being defined with 
the command. The address can be designated in hex (leading “Ox” or 
“OX”), octal (leading 0), or decimal 

• access is an optional parameter which indicates the access restrictions of 
the specified region. Access can be “RO” (read only), “WO” (write only), 
”NA” (no access), or “RW” (read/write). If not specified, access defaults to 

“RW”. 

• size is an optional parameter which is used on JTAG ethernet and JTAG 
parallel port RISCWatch targets. It is a decimal number which indicates the 
maximum access byte size RISCWatch can use when reading or writing 
the specified memory region. Size can be 0,1,2, 4, or 8, with each multiple 
identifying a unique PowerPC load/store instruction to use. For example, 
an access size of “4” instructs RISCWatch to read memory by executing 
the “load word” PowerPC instruction. If no access size is specified, the 
default size defined for the target processor will be used. A size of “0” also 
indicates that the default size, used for RISCWatch internal address 
checking, should be used. 

• type is an optional parameter indicating the valid type of access for the 
specified memory region. Valid types are IMEM (instruction memory), 
DMEM (data memory), or MEM (instruction and data memory). If not 
specified on the command, the type defaults to MEM. Since users are not 
aware of the internal access types used for the various RISCWatch 
screens, the default setting of MEM should normally be used. 

Note: Additional variations of the memacc command are possible but not 

pertinent to this discussion. See memacc on page 5-81 for additional 

information. 

Examples: 

memacc add 0x40000000 0x40000009 RW 1 
memacc add OxFFFFOOOO OxFFFFFFFF RO 4 
memacc add 0x4000000a 0x4FFFFFFF NA 

Each “memacc add” command adds an entry to a list of user defined address 
definitions. When RISCWatch performs a memory operation, address validation 
proceeds as follows: 

1. Check the user defined address regions first to determine if the address 
can be read/written. Entries are searched LIFO, meaning the last 
“memacc add” command entered is checked before any previous entries. 
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2. Perform the internal address checking defined for the target processor for 
any portion of the address range not included in the user defined entries. 

Practical Application Example 

The following example is provided to demonstrate how the memacc command can 
be used to customize RISCWatch memory access. 

Example: 

1. RISCWatch is running on a customized chip that is built around the Pow¬ 
erPC 401 Core. 

2. There is a two byte region of memory, starting at address 0x50004444, 
which can be accessed with the load/store halfword PowerPC instruc¬ 
tions. 

3. All other addresses, starting at 0x50000000 and ending at 0x5FFFFFFF, 
are considered invalid. A store or load to any one of these addresses will 
result in a machine check. 

4. Memory mapped 10 addresses 0x40000000 to 0x40000009 are one byte 
read/write access locations used for serial port operations. Addresses 
0x4000000A to 0x4FFFFFFF are invalid 

5. All other addresses are valid read/write regions which can be accessed 
via the PowerPC load/store word instructions. 

Based on the target processor, RISCWatch is set up to perform internal address 
checking: 

• Every address, from 0x00000000 to OxFFFFFFFF, is valid for both read 
and write operations. 

• Access size defaults to 4. This means PowerPC load/store word 
instructions can be used to access memory. 

Note: The user always has the option of not using any of the RISCWatch 
internal address checking. This is accomplished by completely defining the 
entire address space with “memacc add" commands. For example, “memacc 
add 0 OxFFFFFFFF” defines the entire address space as a read/write region 
of 4 byte access size. With all possible addresses defined, there is no need 
for RISCWatch to perform any internal address checking. 

Using the default internal checking as a base, “memacc add” commands must be 
issued to indicate all address regions that do not allow 4 byte read/write access. 
These would be all the addresses from 0x40000000 to 0x5FFFFFFF. 

The following commands should be added to the RISCWatch start-up command 
file (designated with the STARTUP_FILE environment variable): 

1. memacc add 0x50000000 0x5FFFFFFF NA 

2. memacc add 0x50004444 0x50004445 RW 2 
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3. memacc add 0x40000000 0x40000009 RW 1 

4. memacc add 0x4000000a 0x4FFFFFFF NA 

Note: Notice the addresses overlap between the first and second commands. 

Since the second command is issued after the first, RISCWatch will use the 

restrictions of the second command, since LIFO search order is used. 

RISCWatch is now customized to the unique memory constraints presented in this 
example. Any attempt to read/write memory addresses 0x0400000a to 
0x50004444, or 0x50004446 to 0x5FFFFFFF, will be flagged as an error and the 
memory access will not be attempted. Any attempt to read/write memory 
addresses 0x40000000 to 0x40000009 will be performed using PowerPC 
load/store byte instructions. PowerPC load/store halfword instructions will be used 
to access the halfword that exists at address 0x50004444. All other address 
regions will be considered valid read/write requests that can be performed using 
PowerPC load/store word instructions. 
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Window Descriptor File 

Once the unique memory access restrictions and register definitions are complete 
(by using the memacc command and creating a Processor Configuration File), 
RISCWatch commands can be issued to read or alter resources which are 
accessible from the core processor. In addition, users can create their own 
customized windows which display Core+ASIC resources. Please see 
“User-Defined Windows” on page 3-119 for details about customized RISCWatch 
windows. 


Multi-Processor Resources 

In an effort to support multi-processor PowerPC systems, RISCWatch allows a 
user to create a Multi-Processor Support (MPS) file. This file, created prior to 
starting RISCWatch, contains information which allows a single RISCWatch 
session to communicate to each processor. 

Currently, certain restrictions apply when running RISCWatch in a multi-processor 
environment: 

• All PowerPC processors must be identical. For example, RISCWatch can 
not currently debug both a 403GA and 603e processor from a single 
session. 

• For JTAG targets, each processor must be the only device on the JTAG 
scan chain. 

• Only one parallel port target is allowed. 

• The target processor scan chain can not contain multiple devices. 

The following sections provide additional details needed to run RISCWatch in a 
multi-processor environment. 

MPS File Syntax 

The MPS file is an ASCII file that can be created with any text editor. The file is 
identified to RISCWatch via the MPS_FILE environment variable, and must have a 
file extension of “.mps”. 

The general syntax rules are as follows: 

1. The “#” character denotes the start of a comment. All text following the “#” 
character on a given line will be ignored. 

2. Blank lines are allowed and will be ignored. 

3. Any error detected during the processing of the MPS file will surface an 
error message in the RISCWatch log file and execution will terminate. 
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Board Definitions 


Board definitions span multiple lines of the file and are used to identify the type of 
PowerPC chip on a board and the communication protocol RISCWatch should 
use. Each board definition must adhere to the following syntax: 

BOARD brd_name target_name [target_type [wbg [wfg [cbg [cfg [tbg [f/g]]]]]]] 
CHIP procjd chip_name ir bypass length 

ENDBOARD 

Where: 


• BOARD indicates the start of a new board definition and must appear in 
uppercase. 

• brd_name indicates a user defined name for the board. The name must be 
enclosed in double quotes. Names exceeding 24 characters will be 
truncated. 

• target_name indicates a valid target name found in the TCP/IP services file 
or a TCP/IP dotted address (e.g. 7.1.1.100). This overrides any 
TARGET_NAME designation made in the rwppc.env file. 

• target_type indicates the type of RISCWatch target to use. Valid target 
types are those defined for the TARGET_TYPE environment variable. See 
“Environment Resources” on page 3-5 for valid target types to use. If the 
target type is not designated, the default JTAG_ETH is used. 

• wbg indicates the window background color to use for all RISCWatch 
windows associated with this board definition. See color on page 5-32 for 
valid color designations. A value of “DEFAULT” indicates to use the host 
system default. 

• wig indicates the window foreground color to use for all RISCWatch 
windows associated with this board definition. See the command color on 
page 5-32 for valid color designations. A value of “DEFAULT” indicates to 
use the host system default. 

• cbg indicates the control button background color to use for all RISCWatch 
windows associated with this board definition. See color on page 5-32 for 
valid color designations. A value of “DEFAULT” indicates to use the host 
system default. 

• cfg indicates the control button foreground color to use for all RISCWatch 
windows associated with this board definition. See color on page 5-32 for 
valid color designations. A value of “DEFAULT” indicates to use the host 
system default. 

• tbg indicates the text background color to use for all RISCWatch windows 
associated with this board definition. See color on page 5-32 for valid 
color designations. A value of “DEFAULT” indicates to use the host system 
default. 
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• tfg indicates the text foreground color to use for all RISCWatch windows 
associated with this board definition. See color on page 5-32 for valid 
color designations. A value of “DEFAULT” indicates to use the host system 
default. 

• CHIP is a keyword indicating chip information will follow. It must be 
designated in uppercase. At least one chip entry must be designated for 
each board defined or a syntax error will occur. 

• procjd indicates a valid processor target name. Valid processor names 
are those defined for the PROC environment variable. See “Environment 
Resources” on page 3-5 for valid processor names to use. 

• chip_name indicates a user defined name for the chip. The name must be 
enclosed in double quotes. Names exceeding 24 characters will be 
truncated. 

• ir is a decimal number indicating the bit size of the JTAG instruction 
register. 

• bypass is a value used to put this chip in JTAG bypass mode. The value 
can be specified in hex (leading “Ox” or “OX”) or decimal. 

• length indicates the number of bits on the scan chain when this chip is put 
in JTAG bypass mode. 

Note: The bypass and length fields are required when the JTAG scan chain 
has more than one chip hooked up to it. In this case, multiple CHIP records 
would be defined for a single board. As noted earlier, this type of configuration 
is currently not supported. 

Example: 

BOARD “BRD1” 7.1.1.100 jtag_eth BLUE WHITE 
CHIP 403GCX “chip_a” 4 OxF 1 
ENDBOARD 

BOARD “BRD2” 7.1.1.21 jtag_eth RED WHITE RED WHITE BLACK WHITE 
CHIP 403GCX “chip_b” 4 OxF 1 
ENDBOARD 


In the above example, RISCWatch will be initialized to communicate with two 
boards. The 403GCX chip on the first board will be identified as “chip_a”, and the 
second board’s chip will be called “chip_b”. All windows containing a blue 
background will be for “chip_a”, while those having a red background will be for 
“chip_b”. 

When an MPS file is designated, the TARGET NAME and TARGET_TYPE 
environment variable designations (specified in the rwppc.envfile) will be ignored. 
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MPS Debugging 

When RISCWatch is started, the MPS_FILE environment variable setting is 
detected in the rwppc.env environment file. If the specified file is found, it is read 
in and used to put RISCWatch in MPS mode. The file is located using the 
following rules: 

• If the file name is qualified (directory path indicated), the file search is 
performed using the specified directory only. 

• If the name is not qualified, the file search is performed using the directory 
paths designated with the RISCWatch SEARCH_PATH environment 
variable. If not found, the current directory is searched. 

Once in MPS mode, RISCWatch has the ability to switch its communications to a 
target amongst the chips that were specified in the MPS file. This switching ability 
allows for the resources of a particular chip to be specified and debugged as 
though it were a single chip system. The following sections contain more 
information on how individual chips are identified and debugged using the 
RISCWatch interface. 

MPS Context 

At any given moment, RISCWatch can only communicate with a single chip. In an 
MPS environment, it is necessary to debug the resources of several chips which 
may reside on physically separate boards. To communicate with each individual 
chip, there must be a way for RISCWatch to switch its communications path to 
“talk” to a particular chip. 

The resources specified in the MPS file define the communications paths 
RISCWatch will use to communicate with all the chips in the MPS system. The 
target names and types that were specified are used to select the proper physical 
communications path. These resources are managed internally by RISCWatch 
and are transparent to the end user. 

The chip names specified in the MPS file are used to uniquely identify a particular 
chip on a particular board. These names serve as a way for the user to 
communicate to RISCWatch which chip’s resources are to be debugged. To 
switch the communications path to talk to a particular chip, the mpsset command 
is used. 

The argument supplied to the mpsset command is simply the chip name specified 
in the MPS file. RISCWatch is then able to use this name to look up the 
communications path to the specified chip. RISCWatch configures its 
communications so that it is able to debug the resources of the specified chip. 
Using the mpsset command is referred to as setting the MPS context. It is within 
this context that a particular chip’s resources will be accessed. 
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The RISCWatch Main window will be the primary means of identifying what MPS 
context is currently set. The status bar, located at the bottom of the Main window, 
will display the name of the chip which is currently being debugged. 

The MPS context is said to have been set to this chip that is displayed in the status 
bar. Any command issued from the command line on the Main window will 
execute in this context. If a read register command is executed, the specified 
register will be read from the current MPS context (the chip displayed in the status 
bar). If a register from a different chip is to be read, the mpsset command must be 
issued to switch the MPS context to that chip and then the ’’read register” 
command can be used. 

When running a command file, the commands are executed under the current 
MPS context. To switch the context during execution of the command file, simply 
issue mpsset as necessary. 

MPS Windows 

In MPS mode, windows are classified as being one of three types: 

MPS dynamic 
MPS specific 
MPS neutral 

The RISCWatch Main window is the only instance of an MPS dynamic window. 
This window can have its MPS context switched by using the mpsset command. 
Its current MPS context is displayed in the status bar. 

MPS specific windows are assigned the current MPS context upon creation and 
its MPS context can not be changed thereafter. Any processor accesses or 
commands issued from such a window will only pertain to its MPS context and no 
other. The MPS context for each of these windows will be displayed in the 
window’s title bar. What will be displayed is the chip name assigned to that MPS 
context in the MPS file. Most windows in RISCWatch are MPS specific. 

MPS neutral windows are assigned no MPS context because they do not access 
processor resources or they simply use the current context (as displayed in the 
Main window status bar). Examples of MPS neutral windows include Calculator, 
Command File, Log, Memory Load, Memory Save, MPS, Output and Window List. 

The MPS window is only available in MPS mode and is used as a shortcut to set 
the MPS context as well as providing status for each chip. Displayed in this 
window are all the boards and chips defined in the MPS file. The mouse is used to 
select a chip which in turn issues the appropriate mpsset command to switch the 
MPS context to this chip. 
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Invoking the Debugger 

Before RISCWatch is started for the first time, a few items need to be taken care 
of. First, make sure that the RISCWatch executable is in a directory that can be 
located by the PATH environment variable. Prior to starting RISCWatch, change 
the environment resource file rwppc.env to match the specific target 
configuration you plan to use. Below is the complete list of the different target 
types available and a brief description of some of the key steps that need to be 
taken. See “Environment Resources” on page 3-5 for additional resource setup 
information. 

• JTAG Parallel Port Target: 

Verify that the JTAG hardware was installed as defined in the RISCWatch 
Debugger Installation Guide. 

Verify that the rwppc.env file designates ‘TARGET_TYPE = jtag_par’, as dis¬ 
cussed in “Environment Resources” on page 3-5. 

• JTAG Ethernet Target (RISCWatch Processor Probe Connection): 

Verify that the Processor Probe hardware was installed as defined in the 
RISCWatch Debugger Installation Guide. 

Verify that the rwppc.env file designates ‘TARGET_TYPE = jtag_eth’, as dis¬ 

cussed in “Environment Resources” on page 3-5. 

Verify that the rwppc.env file designates ‘TARGET_NAME = x...x’, where 
‘x...x’ is replaced by the TCP/IP name or address chosen for the processor 
probe during installation. 

Verify proper installation and network recognition of the RISCWatch Proces¬ 
sor Probe. This can be accomplished by ‘pinging’ the TARGET_NAME from 
the host system (ex. ‘ping 7.1.1.100’). 

• ROM Monitor Target: 

Verify that the host is configured correctly for Ethernet setup, as discussed in 
the configuration section of the evaluation board kit user’s documentation. 
These instructions describe specific host configuration steps and other setup 
(editing /etc/services files) required by RISCWatch for successful host/target 
communication. 

Verify that the target ROM monitor is set up in debug mode, as discussed in 
the IBM PowerPC evaluation board kit user’s documentation. This typically 
involves starting a terminal emulation screen, resetting the board, enabling an 
ethernet or serial port boot source, and selecting an option to enable ROM 
monitor debug. 
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Verify that the rwppc.env file designates ‘TARGET TYPE = rom_mon’ as dis¬ 
cussed in “Environment Resources” on page 3-5. 

Verify that the rwppc.env file designates TARGET_NAME = x...x’, where 
‘x...x’ is replaced by the TCP/IP name or address chosen for the ROM moni¬ 
tor. See the IBM PowerPC evaluation board kit user’s documentation for more 
information about setting up a local address for the ROM monitor. 

From the host system, ping the TARGET_NAME to verify proper network and 
ROM monitor initialization (ex ‘ping 7.1.1.4’). Note that the ROM monitor must 
be in debug mode when the ping command is issued. 

• OS Open Target 

Verify that OS Open is running on the target system. RISCWatch cannot com¬ 
municate with OS Open programs that have not called rsld_start(). Loading 
an OS Open image can be performed using one of the other RISCWatch tar¬ 
gets (see “Loading Boot and Boot Image Files” on page 3-46) or by using 
ROM monitor bootp support. See the IBM PowerPC evaluation board kit 
user’s documentation and the OS Open User’s Guide, listed in “Related IBM 
Publications” on page xxiv of this user’s guide. 

Verify that the rwppc.env file designates ‘TARGET_TYPE = osopen’ as dis¬ 
cussed in “Environment Resources” on page 3-5. 

Verify that the rwppc.env file designates ‘TARGET_NAME = x...x’, where 
‘x...x’ is replaced by the TCP/IP address chosen for the OS Open image. 

From the host system, ping the TARGET_NAME to verify proper network and 
OS Open initialization (ex ‘ping 7.1.1.4’). 

Under normal circumstances, RISCWatch will be started as described in “Starting 
the Debugger” on page 2-1. RISCWatch does have a few command line 
parameters which may or may not have to be specified depending on how you run 
RISCWatch. Here is a list of the command line parameters that RISCWatch 
understands: 


-echo 


-help or ? 
-procNAME 


used to echo each command file line as it is executed; use 
this to debug command file execution. This option is only 
available on a non-PC platform. 

used to display the help information for RISCWatch which 
lists all of the available command line options 

overrides PROC setting specified in the environment 
resources file (rwppc.env). This allows multiple icons on 
PC hosts to be defined for different processors while using 
only one environment file. 

See the README file for a list of currently supported 
processor names. 


3-34 


RISCWatch Debugger User's Guide 



-rev Overrides REV setting specified in the environment 

resources file. This distinguishes between different 6xx/7xx 
processor revision levels when connected via the 
RISCWatch Processor Probe. The -rev flag must be used 
when debugging a 6xx/7xx processor in which RISCWatch 
supports more than one revision level. For example, if 
debugging a 603e Rev3 processor, one would use -rev3 to 
distinguish Revision 3 from other supported revision levels. 
Once the proper JTAG driver is loaded into the Processor 
Probe memory, the -rev flag is not required. 

If RISCWatch only supports one revision level of a given 
processor, the -rev flag is not required. 

-tty specifies that RISCWatch is to be run in TTY mode. TTY 

mode is a command line driven mode of RISCWatch that 
does not rely on the user interface for input and output. 
This option is only available on a non-PC host. 

JTAG Ethernet Targets and the RISCWatch Processor Probe 

The RISCWatch processor probe is an Ethernet-to-JTAG convertor, converting 
commands sent from RISCWatch to the appropriate series of processor accesses 
through the JTAG port of the probe. The probe has a dedicated JTAG controller 
chip to drive the JTAG signals in hardware as opposed to a slower, emulated 
approach in software. 

To talk to RISCWatch, the processor probe contains two programs in its flash 
memory: the interface that RISCWatch communicates with (called the 
“Generics”), and the underlying specific JTAG device driver. When a RISCWatch 
JTAG Ethernet target is initially invoked, RISCWatch will check the version of the 
Generics and the specific JTAG driver loaded in the processor probe (or 
requested with the -proc flag or PROC environment variable) against the versions 
of the files located in the directory specified by the RWPPC_DIR environment 
variable. If the Generics or JTAG drivers do not match, the file(s) from the 
RWPPC_DIR will be loaded into the processor probe. Because loading the 
processor probe may corrupt the processor’s JTAG controller, it is recommended 
that the processor be reset after the loading is complete. 

Note: If you wish to maintain the current processor state, the processor probe 
must be disconnected from the target until the correct Generics and JTAG driver 
are loaded. 

Generics and JTAG driver filenames supported for currently available processors 
are included in the README file provided for this version of RISCWatch. 

The following are some considerations to note when using the Processor Probe: 
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• For JTAG connections, the target processor clock speed must be at least 
twice the JTAG clock speed. For Processor Probe targets the JTAG clock 
speed defaults to lOMhz. The RISCWatch command ‘jtag’ (see p. 5-69) can 
be used to lower the JTAG clock speed. Because of the high speed of the 
JTAG interface with the Processor Probe, it is possible that noise on the 
interface to the target may adversely affect data passed between RISCWatch 
and the target. If memory or register reads appear to be unstable when using 
a processor probe connection, see if using the ‘jtag’ command to lower the 
JTAG clock speed fixes the problem. 

• RISCWatch will attempt to update the Processor Probe flash memory if it 
detects that the processor type desired for the RISCWatch session does not 
match the processor type which the Processor Probe is currently initialized for 
(this behavior may be overridden by using the PROBE_FLASH environment 
variable).Updating the Processor Probe flash memory with the JTAG 
connector connected to the target typically puts the processor into an 
unrecoverable state. Therefore, RISCWatch will always attempt to reset the 
processor after the Processor Probe flash memory is updated. 

• The PROBE_FLASH environment variable can be used to disable updates to 
the Processor Probe flash memory. See “Environment Resources," p. 3-5 for 
details on how to force, or completely bypass, a reflash of the Processor 
Probe. 

• The suggested procedure when updating the Processor Probe flash memory 
is as follows: 

1. Start with the Processor Probe connected to the target. 

2. Following the update of the flash, if you got a warning message saying 
RISCWatch was unable to soft stop the processor while RISCWatch was 
coming up, attempt to reset the target from RISCWatch via the ‘reset’ 
command or Reset window. 

3. If the reset from RISCWatch fails, reset the target via its reset switch. If 
that doesn’t satisfactorily reset the entire board, a power on reset will be 
required on the target. 

4. Following the reset, enter the ‘stop’ command from RISCWatch to start 
debugging. 

Operational Notes: 

• Disconnecting/connecting the Processor Probe from/to the target while power 
is applied may affect the state of the target and a reset of the target may be 
required. 

• Cycling power on the Processor Probe typically puts the target in an 
unrecoverable state and a reset of the target will be required. Always wait for 
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the LEDs on the front of the Processor Probe to stop blinking before resetting 
the target. 

RISCWatch will not allow more than one copy of RISCWatch to communicate 
with the Processor Probe at one time. If the Processor Probe is in use, the 
error message “communications port already in use” will appear. In some 
conditions the communications link may not close correctly, thereby locking 
out RISCWatch from coming up again. A couple of the more common 
situations where this may occur are: 

• Rebooting a PC while RISCWatch is running 

• Disconnecting the Processor Probe from the host while 
RISCWatch is running, and subsequently terminating that 
RISCWatch session with the Processor Probe still disconnected. 

If this condition occurs, cycling power on the Processor probe will clear the 
communications link. 
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Main Window Resources 


RISCWatch employs a graphical user interface (GUI) that needs to have the host 
platform window system running. 

When RISCWatch is started, it will bring up the windows specified in the 
rwppc.lay file. The first time RISCWatch is run, or at any other time when no 
rwppc.lay file is available, or if LOAD_LAYOUT = NO is specified in the 
environment file, the debugger brings up only the main command window. It is this 
window, shown in Figure 3-1, that will be used to access all of the debugger 
features. 


RISCWatch 


File Source Hardware Window Utilities 


Help 


srchpath set /u/rwppc/examples 
load file Dhrystone 


Command 


STATUS : loading .data (1160(0x488) bytes @ 0x00030020) 
STATUS : Initializing .bss (10396(0x2890 bytes @ 
0x00030488) 

STATUS : Stack ptr = 0x0003C170 
STATUS : load successful 


Welcome to RISCWatch v4.00 

No MPS 

403GA 

JTAG 


Figure 3-1. Sample Main Window 

Note: The list of items found at the bottom of the screen may be different 
depending on the level of RISCWatch, target type, etc. 


At the top of the window resides the menu bar which contains the names of the 
major program access points. Directly below the menu bar is a scrolling window 
which maintains a history of all the commands entered through the command line 
interface. Commands in this window can be re-executed or edited and then 
executed as described in “Command History Usage” on page 3-42. 
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Directly below the command history window is the command line interface that is 
used to send commands to RISCWatch to be processed. The commands entered 
here are the same as the ones which may be used in a command file to help 
automate development and testing of products using supported PowerPC 
processors. For a list of the commands and their syntax, select the Help option 
from the menu bar. 

Directly beneath the command line interface, is the scrolling message window 
which maintains a history of all entered commands and their resultant status, help 
and error messages. As each command is entered, it is echoed to this window 
and will be followed by status or error messages. This format allows all commands 
and their resultant actions to be viewed at any time. 

At the bottom of the Main Window resides a status bar, which displays updated 
information about current debug activity. A message area shows progress 
messages. An MPS area indicates whether or not multiprocessor support is 
enabled. A chip area identifies the chip name corresponding to the current debug 
context. A target type area indicates the method of communication being used for 
the current debug session. A processor status field also indicates whether the 
target processor is either running, stopped, halted, powered off, or if the status is 
unknown. 


Menus 


The RISCWatch menus are used to access those parts of the program which 
require interaction with the user. Menu items can be commands or sub-menus. 
Selecting an item runs its corresponding command or displays its corresponding 
sub-menu. 

Menu items can be selected by clicking on a menu option to pull down the 
corresponding menu. Moving the mouse to a menu item highlights the item. 
Clicking on a highlighted item selects the item. Unavailable selections are 
grayed-out. Clicking outside the menu closes the menu without making a 
selection. 

Clicking on a menu displays a pull-down containing the selections for that 
particular menu, as shown in “Main Window Menu Options” on page 3-40. 
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File Menu 


Command File (See p. 3-133.) 

Load 

Save 

View 

Quit 


Main 

Window 

Menu 

Options 


Source Menu - Breakpoints (See p. 3-73.) 

Callers (See p. 3-60.) 

Files (See p. 3-61.) 
Functions (See p. 3-62.) 
Globals (See p. 3-79.) 
Locals (See p. 3-77.) 

OS Open (See p. 3-66.) 
Programs (See p. 3-58.) 
Source (See p. 3-51.) 

Hardware Menu - Asm Debug (See p. 3-54.) 

Memory (See p. 3-104.) 
Register (See p. 3-117.) 
Reg Fields (See p. 3-118.) 
Reset (See p. 3-138.) 
Trigger/Trace (See p. 4-8.) 


Window Menu - Calculator (See p. 3-143.) 

Win List (See p. 3-141.) 
Output (See p. 3-135.) 

Win List (See p. 3-141.) 
User-Defined (See p. 3-119.) 


Utilities Menu - Beep (See p. 3-42.) 

Logging (See p. 3-141.) 


Help Menu - About 

FAQ 

Install Guide 
PowerPC Manuals 
User's Guide 


Figure 3-2. Main Window Menu Options 
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The menu bar contains the following menus: 

• File 

• Source 

• Hardware 

• Window 

• Utilities 

• Help 

What follows is a list of the menus and their selections. Next to each selection is a 
brief description of its function. 

File Menu 

Command File Run a command file 
Load Load a memory/register/layout file 

Save Save a memory/register/layout file 

View View a selected file 

Quit Terminate the program 


Source Menu 

Breakpoints window 
Callers window 
Files window 
Functions window 
Globals window 
Locals window 
OS Open window 

Programs window 
Source window 


Displays breakpoints 
Displays called functions 
Displays files in current context 
Displays functions in current context 
Displays global variables 
Displays local variables 

Display OS Open threads and status 
(OS Open target only) 

Displays programs in current context 
Displays source file in current context 


Hardware Menu 

Asm. Debug 
Memory 
Register 
Reg Fields 
Reset 

Trigger/Trace 


Displays the Assembly Debug window 
Displays memory window pull-down 
Displays a register access window 
Displays a register field access window 

Reset the processor, or display a reset window 
(JTAG target only) 

Displays the Hardware Trigger/Trace window 
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Window Menu 

Calculator 
Win List 
Output 
User-Defined 


Displays the desktop Calculator window 
Display window list 

Command Message Output information window 
Loads a user-defined window 


Utilities Menu 

Beep Turns the program error beep on or off 

Logging Enable/disable logging and give current logging status 


Help Menu 


About 

FAQ 

Install Guide 
PowerPC Manuals 
User’s Guide 


Display RISCWatch version information 

Frequently asked questions 

Display RISCWatch User’s Guide 

Display links to various PowerPC documentation 

Display RISCWatch User’s Guide 


Command Line Usage 

RISCWatch supports a rich set of commands which are used to access processor 
resources, thereby facilitating debug of software and hardware. A list of 
RISCWatch commands and their syntax is given in the section “Command Quick 
Reference” on page 5-4. 

These commands may be typed into a command file to be executed by 
RISCWatch or used in the user interface via the command line. The command 
line is the interface between RISCWatch and the user. It is simply a single-line text 
editor that is used to compose commands and their arguments. 

Commands that are valid from the command line may also be entered on the input 
line, as described in “Input Line Usage” on page 3-48. 

The command line understands all alphanumeric keys as well as the Enter, 
Backspace, Delete, Insert, Plome, End and arrow keys. 


Command History Usage 

The RISCWatch Main window maintains a list of all commands the program has 
executed since it was started. This list consists of a scrollable window located 
between the menu bar and command line interface. 

After more than a few commands have been entered, the scroll bar attached to 
the window will need to be used to view the commands which have scrolled off. 
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By using the scroll bar attached to the window, it is possible to view all the 
commands entered since RISCWatch was started. This proves helpful at times to 
see the precise order in which the commands were issued. 

The command history list is also useful for editing or executing previously entered 
commands. To edit a previous command, simply place the mouse over the 
command and click the left mouse button. RISCWatch will place the command on 
the command line where it may be edited and executed if desired. The up arrow 
and down arrow keys can also be used to retrieve previously issued commands 
from the command history list. The up arrow key navigates sequentially back 
through the list while the down arrow moves forward through the list. 

To execute a previously entered command, simply place the mouse over the 
command and double-click the left mouse button. RISCWatch will execute the 
command as though it had been typed in by the user. 

The up and down arrow keys may also be used to sequentially scroll through the 
history of entered commands. As each command is recalled in turn, it will appear 
on the command line. From there it may be edited as desired and executed. 

Message Window 

The message window is located at the bottom of the RISCWatch Main window. 
Every time a command is entered into the command line interface, it is echoed in 
this window. It will then be followed by status or error messages indicating the 
result of the execution of the command. After a few commands have been 
entered, it will be necessary to use the scroll bar attached to the window to view 
earlier commands because they have been scrolled off to show the latest ones. 

The message window is not editable and is used as feedback to the user as well 
as maintaining a history of command usage and status. The contents of the 
message window will be very similar to that of a RISCWatch log file, which is 
described in “Log Files” on page 3-141. 


Running Your Programs 
Preparing the Program for Debug 

Generally, for source level debug, a program must be compiled with a debug 
option selected. Additionally, no optimization option can be used. Also, the target 
processor architecture must be specified as PowerPC. All libraries used must also 
be statically linked into the program unless they already reside on the target. 

For specifics about compiling and linking programs for debugging, refer to the 
documentation included with the compiler and linker being used. 
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For compiling and linking programs intended for use with the PowerPC 400Series 
Evaluation Board Kits, refer to the documentation for the kit being used. 

Loading Files 

Files can be loaded either from the command line in the Main window, or by using 
the File|Load pulldown. Refer to the command reference for the complete list of 
options available for the load command. Enter the command and desired options 
on the command line and hit enter. 

To load a file using the load pulldown, select the file to be loaded. Additional 
prompts will be presented to allow the user to specify the file format and any other 
applicable options. See “Load Memory Window” on page 3-63 for more 
information. 

For source level debug, loading a file includes both target and host initialization. 
The target embedded system is typically initialized with the text and data sections 
of the file. The host system is initialized with the symbolic debug sections of the 
file (symbol table, line table, etc.). If the debugger has not been initialized to debug 
a program via load, start_thread, attach, or restart, all source level debug 
capabilities are disabled. 

To facilitate source level debug on applications which are resident on the target 
prior to RISCWatch invocation, the load command provides the ‘host’ keyword 
which will load the symbolic debug information on the host without changing the 
state of the target system. This method of loading is quite useful when debugging 
ROM resident code. 

The actions performed during the load are summarized below. 

For ROM Monitor and JTAG targets: 

1. A load file command will unload ALL previously loaded files. 

2. A load host filename command will unload only the filename being 
loaded, if it is already loaded. 

3. A load host filename must either be statically linked at the desired 
text/data locations or the text/data parameters must be supplied with the 
load command (that is, load information is not retrieved from the target). 
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For an OS Open target: 

1 . A load file filename will be assumed to be a dynamic load. A load info will 
be issued after the target load. All programs included in the return block 
will be loaded on the host. If the target program, that is, the program 
specified in the load command, is already on the host, it will be unloaded 
and then reloaded. If other programs are already on the host, they will 
remain loaded, that is, they will not be reloaded. 

Any other programs loaded on the host but not included in the load info 
return block will be left alone. 

2. A load host filename must either be statically linked at the desired 
text/data locations or the text/data parameters must be supplied with the 
load command (that is, load information is not retrieved from the target). 

3. A start_thread or attach will behave as the load file except the target will 
not be loaded. 
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Loading Boot and Boot Image Files 

A boot file is defined to be an XCOFF or ELF file which was created with entry 
code consistent with an OS Open executable or a PowerPC 400Series evaluation 
board support package executable. This type of executable was never designed to 
run successfully on the target system. 

The PowerPC 400Series evaluation board support package provides a boot 
image program which takes a boot file and creates a boot image file. The boot 
image file contains a 32 byte header, followed by a binary image of the loadable 
portions of the ELF or XCOFF file. This file may also contain additional binary 
data (controlled by options on the ‘boot image’ program) which is required for OS 
Open use (symbol table, string table, etc.). 

To facilitate the user in debugging boot files, the load file command attempts to 
recognize a boot executable. This is done by looking for the hex number 
‘004d5054’ four bytes beyond the designated entry point. If this special sequence 
is found, RISCWatch will edit the text section of the executable in an attempt to 
make the code execute without the need of loading the boot image file. In addition, 
the symbol and string table is loaded on the target system if the ‘nosym’ flag is not 
designated. This method of loading has proven to be effective on non-OS Open 
boot files. 

It is important to note that the entry code in a boot file load executes differently 
from the entry code provided in a boot image file. For this reason, the load image 
command has been added to allow the user to load a boot image file. RISCWatch 
will strip off the 32-byte header of the boot image file and load the remaining bytes 
of the file on the target. The start address of the load is designated in bytes 3-7 of 
the header. Once loaded, the IAR register is set to the value designated in bytes 
16-19 of the header. 

The following actions and descriptions define three typical debug scenarios using 
boot and boot image files 

• Load and Debug of a Boot File 

1 . Issue the load file command to load the host and target. 

2. This provides full-function support with restart capability. 

3. Entry code is modified by RISCWatch to allow execution. 

• Load and Debug of a Boot Image File 

1 . Issue the load image command to load the target. 

2. Issue the load host command to load the debug information on the host 
system. 

3. Entry code runs exactly as intended without modification. 
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4. Program restart is accomplished by reissuing the load image command. 

• Load and Debug of OS Open Threads 

1. Bring up RISCWatch using the ROM Monitor target. 

2. Hide all windows except the Main window. 

3. Issue the load image command with the filename of the OS Open boot 
image file. 

4. Issue the command logoff. The ROM Monitor will exit debug mode and 
start the execution of OS Open. If a terminal emulation screen is up, you 
should see the OS Open shell prompt. 

5. Select ‘file’ on the Main window and then select ‘quit’ to exit RISCWatch. 

6. Edit the environment file (rwppc.env). Change the TARGET_TYPE to 
‘osopen’. Make sure the TARGET_NAME matches the name or address 
used by your OS Open image. 

7. Bring up RISCWatch using the OS Open target. 

8. Issue a start_thread or attach command to the thread you want to 
debug. 

9. Note that steps 1-6 are required to load OS Open. These steps are not 
required if some other method is used to load OS Open. 

Executing the Program 

Once a file has been loaded successfully, it can be started by issuing the run 
command from the Main window, or by pressing the Run button on the Source or 
Assembly Debug window. Note that the debugger may not automatically stop 
when it gets to the end of the program. Breakpoints or other mechanisms should 
be used to prevent the program from running into non-program memory locations 
upon execution completion. 

When a program is initially loaded, the Instruction Pointer will often be pointing to 
start-up code which has no corresponding source files for the debugger to use. A 
message will be displayed when this situation occurs. In these cases, a breakpoint 
can first be set in the application code and, when it is hit, the debugger context will 
be updated for the current Instruction Pointer. The source code will then appear in 
the Source window. 

Following Program Execution Flow 

Program flow is usually followed with a series of actions that cause the program to 
start and stop at various locations of interest throughout the code. Some of the 
actions that control program execution include: 
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1 . Setting breakpoints and running to them (run) 

2. Stepping one source line (linestep) 

3. Stepping into a function (callstep) 

4. Returning from a function (retstep) 

5. Stepping one assembler instruction (asmstep) 

6. Restarting a program (restart) 

These commands can be executed from the command line, as specified in the 
command reference section, or via buttons on the Source and/or Assembly Debug 
windows. 

Tracing back through execution contexts can be performed using the Callers 
window. Refer to the Callers window description and the Quick Start sections for 
more details on how these windows and commands can be used to follow 
program execution flow. 

Input Line Usage 

The RISCWatch input line can be used to provide a shortcut method of performing 
window search and scroll actions. The input line will appear at the top of a 
RISCWatch window if the window has focus and a keyboard character is typed 
which corresponds to a supported function for that window. Table 3-2 describes 
each of the available functions: 


Table 3-2. Input Line Functions 


Key 

Function 

Parameter 

Supported 

Windows 

FI 2 

command line 

Any command line 
command 

all 

/ 

find forward (find 
command) 

search string 

specified in find 
command descrip¬ 
tion 

\ 

find backward 
(findb command) 

search string 

specified in findb 
command descrip¬ 
tion 

? 

find exact (finde 
command) 

search string 

specified in finde 
command descrip¬ 
tion 


3-48 


RISCWatch Debugger User's Guide 



Table 3-2. Input Line Functions 


Key Function 

Parameter 

Supported 

Windows 

: scroll to line (line 

line number 

specified in line 

command) 


command descrip¬ 



tion 

; scroll to source line 

source line number 

Source window 

(srcline command) 




/ [FIND] 


async_ 


■BFs 


* 

FPE mtfsfi; OxOOOlBEDC; FPE mtfsfi.s 

* 

FPE_stfd; OxOOOlBFOO; FPE__stfd.s 


_FPE_stfs; 0x0001BF18; __FPE__stfs.s 


_entry; 0x00010000; noname 


_ptrgl; 0x0001F6CC; ptrgl.s 


ESHilSginit; 0x0001F754; asyncLib.c 


async_init_dds; 0x0001F7EC; asyncLib.c 

* 

async_open; 0x0001F908; asyncLib.c 

* 

async_polled_write; 0x000203AC; asyncLib.c 

* 

async_set_baud_rate; OxOOOlFCOO; asyncLib.c 


-J D 


— Functions display mode - 

V Functions w/ debug info by name 

V Functions w/ debug info by addr. 
• A flll functions by name 

vAll functions by addr. 


Hide 

Help 


Figure 3-3. Sample Input Line Displayed 


The first field of the input line will indicate the function being performed. That will 
be followed by an entry field which can to be used to specify any parameters for 
the function, if necessary. For example, entering a command valid from a 
command line (not all commands can be used from a command line) or searching 
for a string in a window can be done in the input line. 

For example, typing a 7’ character in a window which supports the find command 
will display the input line at the top of the window with the first field specifying T 
[FIND]’. In this case the parameter to be entered in the entry field would be the 
string to search for. 
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Typing the enter key will perform the requested function. Typing the ESC key, or 
performing any mouse action on another window, will hide the input line with no 
action taken. 

Refer to Chapter 5, "Debugger Command Reference," for detailed information 
concerning any of the commands mentioned above. 

The input line automatically uses the associated window (the window which had 
focus when the input line was brought up) as the window parameter for those 
functions which require it. In the case of the Variable Configuration window and 
the Breakpoint Select window, which have more than one subwindow, the 
subwindow to use for an input line function can be selected by clicking the mouse 
in the subwindow (either on an entry or on a blank line) or by selecting a scrollbar, 
with the mouse if it will result in a scrolling event. 

Also for these two windows, selecting one of the ‘Move all to...’ push-button will 
select the subwindow to which the move was done as the subwindow to be used 
for subsequent input line functions. 

If the entry field is left blank for any of the find functions, the last string which was 
specified for a find function will be used as the search string to perform a ‘next’ 
type search for the associated window. 

Note: On some host platforms, if a control in a window has focus, it may be 
necessary to give the window itself focus by clicking the mouse on the window 
background or titlebar before it will recognize keyboard characters. 
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Source Level Debugging 
Source Window 


The Source window consists of a Source File subwindow with a Status 
subwindow, a Source Mode selection groupbox, and pushbuttons. For example, 
Figure 3-4 shows the Source window in Source/Assembly mode. 

The title bar indicates the source file currently being displayed. The file which is 
displayed in the Source window can be changed by performing one of the 
following actions: 

______ I f 

Source (/u /r wppc /examples /dhry «-1 .c) 


Ptr_Glob = (Rec_Pointer> malloc (sizeof (Rec_Type)>; 


000205BC: 

000205C0: 

000205C4: 

000205C8: 

000205CC: 

000205D0: 

000205D4: 


38600030 addi 
4BFF1A29 bl 
4FFFFB82 cror 
389E0000 addi 
38A30000 addi 
8062007C lwz 
90A30000 stw 


R3,0,0x0030 

*+0xFFFFlA28(0x00011FE8) 

31.31.31 

R4'R30,0x0000 

R5,R3,0x0000 

R3,0x0000007C(R2> 

R5,0x00000000<R3> 


89 




90 

Ptr_Glob->Ptr_Comp 

= Next 

* 

000205D8: 80A30000 

lwz 

R5,0x00000000<R3> 

* 

000205DC: 80840000 

lwz 

R4,0x00000000(R4> 

* 

000205E0: 90850000 

stw 

R4,0x00000000(R5> 

91 

Ptr_Glob->Discr 


= Ident 


* SBP >> 


000205E8: 38800000 
000205EC: 90850004 
Ptr_Glob->variant. 
000205F0: 80A30000 
000205F4: 38800002 
000205F8: 90850008 
Ptr_Glob->variant. 
000205FC: 80A30000 
00020600: 38800028 
00020604: 9085000C 
strcpy (Ptr_Glob-> 


addi R4,0,0x0000 

stw R4,0x00000004(R5) 

var_l.Enum_Comp = Ident_3; 

lwz R5,0x00000000<R3> 

addi R4,0,0x0002 

stw R4,0x00000008<R5) 

var_l.Int_Comp = 40; 

lwz R5,0x00000000(R3) 

addi R4,0,0x0028 

stw R4,OxOOOOOOOC(R5> 

variant.var_l.Str_Comp, 


|STOPPED | 

Source disp. 
Source 

■'*' Source/Asm 


Line step 


Call step 


Ret step 


Asm step 
Help 


Figure 3-4. Sample Source Window 
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• Initiate debugging via a command like load, start_thread, attach, or 
restart. 

• If the debugger has not been initialized to debug a program via one of the 
above commands, all source level debug capabilities are disabled. 

• Change the current context as in the case of a breakpoint being hit in 
another file, performing an execution command, or selecting an entry from 
the Callers window. 

• Select an entry from the Files, Functions, or Breakpoints windows using 
the file command 

The title bar will also include the name of the function containing the current 
Instruction Pointer if the following is true: 

• The Source window was updated as a result of an execution action 
completing (stepping, hitting a breakpoint, etc.), and the file in the Source 
window contains the function associated with the current Instruction 
Pointer. 

• The file in the Source window has no debug information. 

In regular Source Mode, a source file which is part of the current program is 
displayed in the Source File subwindow, with the corresponding source line 
numbers displayed in the Status subwindow. In Source/Asm Mode, a source file 
which is part of the current program is displayed in the Source File subwindow, 
with both source lines and assembly instructions displayed. Assembly instructions 
appear for each source line which has instructions associated with it, directly 
below the corresponding source line. In this mode, the Status subwindow shows 
the line number for corresponding source lines, and an asterisk for assembler 
lines. The displayed assembly instructions come from the file image of the loaded 
program. This differs from the instructions displayed on the Assembly Debug 
window, which are determined by reading the target system memory. 

The Source Mode groupbox consists of two buttons, one for Source only and one 
for Source/Asm. The display mode is changed by selecting the appropriate button. 
The button which is on indicates the current mode. If a file is currently displayed 
when the display mode is changed, the window will be updated to show the 
source file in the new mode. Regardless of whether a file is currently displayed, 
any subsequent files which are displayed in the window will be displayed in the 
mode reflected by the button which is on in the Source Mode checkbox. 

The Status subwindow shows source line numbers, denotes assembly 
instructions with an asterisk, indicates the current Instruction Pointer, and 
indicates any instruction breakpoints which are set. A double arrow (») is 
displayed on the line corresponding to the current Instruction Pointer address. In 
Source/Asm mode, this indicator will appear next to the assembly instruction 
associated with the Instruction Pointer address. 

The letters 'BP' will appear on the line corresponding to an instruction breakpoint if 
the Source window is in Source Only mode. In Source/Asm mode, the letters 
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‘SBP’ or ‘HBP’ will appear next to each assembly instruction for which a software 
or hardware breakpoint has been set. Breakpoints can be set or deleted by 
clicking the mouse in the Source subwindow on a valid line. If in Source/Asm 
mode, breakpoints can only be set by clicking on lines corresponding to 
assembler instructions. If a breakpoint cannot be set on a selected line, an error 
message will be generated. 

If the Breakpoint Mode (selectable via the bpmode command or from the 
Breakpoints window) is set to Hardware or Hardware Step, breakpoints can only 
be set on assembler instructions (requiring Source/Asm mode). This is because 
setting a break on some source lines may require setting breakpoints on multiple 
assembly lines associated with the source line (the 'for' statement is an example), 
and only a finite number of hardware breakpoint registers are available at any one 
time. 

Directly below the Status subwindow is the processor/process running indicator. 
This field indicates whether the processor (in the case of a JTAG target) or 
process (in the case of a ROM Monitor or OS Open target) is currently running or 
stopped. If the processor/process is running, the Run/Stop button will be titled 
“Stop”, and the status indicator will be “Running”. Pressing the button in this state 
will cause the processor/process to be stopped. If the processor/process is 
stopped, the Run/Stop button will be titled “Run”, and the status indicator will be 
“Stopped”. Pressing the button in this state will cause the processor/process to 
run. This is the same functionality which exists on the Assembly Debug window 
(see p. 3-57). The status and button state will be updated automatically during the 
course of the debug session to reflect any changes in the processor/process 
state. If the debugger is currently not attached to and debugging a target, the 

status indicator on this window will be a string of periods (“.”). If a 

processor/process is running, all controls or actions are disabled for all source 
level debug windows except for the processor/process status indicator and the 
Run/Stop button on the Source window. 

Breakpoints are toggled by single clicking the mouse on a line in the Status 
subwindow corresponding to a valid source line. If no break is currently set at the 
line, a breakpoint is set by single clicking the mouse on the line, and the bp 
indicator appears in the Status subwindow on that line. Conversely, if a break is 
currently set at the line, a breakpoint is deleted by single clicking the mouse on the 
line, and the bp indicator is removed in the Status subwindow on that line. If a 
breakpoint is set or deleted from the source window, the Breakpoints window is 
updated accordingly. 

For details on how to perform character string search operations, or how to quickly 
scroll to a specific source line number, see “Input Line Usage” on page 3-48. 

• Additional Functions available in Popup Menu 

Holding down the right mouse button in the Source File subwindow will produce a 
popup menu containing a list of additional functions relating to the source window. 
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It allows the user to Go To or Run To a particular source line, to toggle the display 
mode of the source window, and to inspect variables within the file being 
displayed. The Go To option will set the IAR to the location of the address 
corresponding to the first assembly instruction of the source line selected. The 
Run To option will actually set a break at that address and run the processor to the 
target location. The toggle mode option will change the display format of the 
Source File subwindow between Source only and Mixed Source/Assembly 
modes. Choosing the Inspect option will bring up an Inspect Window containing 
the variable selected by the initial right mouse button click. 

Scrolling Source Window Contents Using the Keyboard 

The data contained in a source level debug window with focus can be scrolled 
different ways using the keyboard. Following are the keys which can be used to 
scroll data: 


Table 3-3. Keyboard Options for Scrolling 


Key 

Function 

Up Arrow 

Scroll up one line 

Down Arrow 

Scroll down one line 

Left Arrow 

Scroll left one section 

Right Arrow 

Scroll right one section 

Page Up 

Scroll up one page 

Page Down 

Scroll down one page 

Home 

Scroll to top of contents of window 

End 

Scroll to bottom of contents of window 


Assembly Debug Window 

Assembly level debug can be carried out in several ways. One way is via a source 
disassembly in the Source window. This can be used only when the source file 
has been compiled with debug information. 

Another way to perform assembly level debug is via the Assembly Debug window. 
The Assembly Debug window allows memory to be read, altered and written as 
assembly opcodes and disassembled text. This window uses an actual memory 
disassembly, so it can be used independent of whether the source exists or was 
compiled with debug information. Multiple instances of the Assembly Debug 
window are permitted to show a variety of address ranges simultaneously. The 
screens are distinguishable by an instance number appearing in the window title. 
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Assembly Debug: 1 


l 


Address Data 


Disassembly 



I 


000205E4 80A30000 lwz R5,0x00000000(R3) 

000205E8 38800000 addi R4,0,0x0000 

000205EC 90850004 stw R4,0x00000004(R5) 

000205F0 80A30000 lwz R5,0x00000000<R3> 

000205F4 38800002 addi R4,0,0x0002 

000205F8 90850008 stw R4,0x00000008(R5> 

000205FC 80A30000 lwz R5,0x00000000(R3) 

00020600 38800028 addi R4,0,0x0028 

00020604 9085000C stw R4,OxOOOOOOOC(R5) 

00020608 80630000 lwz R3,0x00000000(R3> 

0002060C 30630010 addic R3,R3,0x0010 

00020610 389F0000 addi R4,R31,0x0000 

00020614 4BFF0015 bl *+0xFFFF0014(0x00010628 

00020618 4FFFFB82 cror 31,31,31 

0002061C 30610038 addic R3,R1,0x0038 

00020620 309F001F addic R4,R31,OxOOlF 




13 


Run 


Asmstep 


Read 


Close 


Help 


STOPPED 


Step count Set IAR 


00000001 


000205E4 


W Track IAR 
_J Show offsets 


Figure 3-5. Sample Assembly Debug Window 


Refer to “Debugging at the Assembly Level” on page 2-14 for an example of how 
assembly level debug can be performed. 

This window is displayed by selecting the Asm Debug option of the menubar's 
Hardware pull-down choice. What follows is a description of this window’s 
functionality. 

• Data area 

The data area for the Assembly Debug window is a large text editing area which 
consists of three parts: memory addresses, data words and disassembled text. 
The memory addresses are listed sequentially in a column along the left hand 
side of the data area. The data words are located in a column adjacent to their 
respective memory addresses. The disassembled text consists of each data word 
being disassembled and then displayed in the adjacent column. 

Each of these areas can be edited thereby allowing addresses or data to be 
altered and then written back to memory. Editing one of the memory address 
values allows for the disassembled display of any piece of memory. Simply use 
the mouse to place the cursor next to one of the addresses. Then type in the new 
address and press the Enter key. The appropriate memory addresses will be read 
from memory, disassembled, and then displayed in the data area. 
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It is also possible to change the memory words or disassembled text. To change a 
particular memory word, simply use the mouse to place the edit cursor next to the 
desired word. Type in the new word and press the Enter key. The newly entered 
value will be written and then the display will be updated with the disassembly text 
for the new word. 

Similarly, the disassembled text may be edited by using the mouse to place the 
edit cursor next to the desired text. Type in the new assembly text and press Enter. 
The assembler will then be called to create a new memory word which will be 
written to the appropriate address. The display will then be updated with the newly 
created memory word. 

Data values entered for new addresses and memory words are expected to be 
input in hexadecimal format. 

• Scroll Bars 

Clicking on a vertical scroll arrow alters the display address by one line or opcode. 
Clicking on the area between a vertical arrow and the current scroll position alters 
the display address by one screen’s worth of data. To display a given address, use 
the address entry schemes described in the Data area section. 

The page up and page down feature may also be accessed via the keyboard Page 
Up and Page Down buttons. 

• Breakpoint subwindow 

The breakpoint subwindow is located to the left of the data area and is used to set, 
clear, and display hardware or software breakpoints. An asterisk appears next to 
each disassembly line shown in the data area when no breakpoints are set on the 
corresponding address. It also is used to perform Run To or Go To actions 
corresponding to the selected memory location. 

To set a hardware or software breakpoint for a particular memory address, simply 
use the mouse to click on the corresponding asterisk. This will set a hardware or 
software breakpoint, depending on the current Breakpoint Mode (selectable via 
the bpmode command or from the Breakpoints window). For that address an 
‘HBP’ or ‘SBP’ marker replaces the asterisk, indicating that a hardware or 
software breakpoint has been set for that address. 

To clear a breakpoint, simply click on the ‘HBP’ or ‘SBP’ marker. This will clear the 
breakpoint and restore the asterisk marker for that memory location. 

To execute the Run To and Go To actions, place the cursor on the asterisk next to 
the desired target address of the action. Then hold down the right mouse button. 
A selection list will appear, allowing the user to choose the desired function. The 
GoTo selection will cause the IAR to be changed to the target address, while the 
RunTo selection will set a break at the target address and run the processor to 
that location. 
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IAR cursor 


The IAR cursor is used to indicate which memory word is being pointed to by the 
IAR register. The IAR cursor appears as the » characters in the breakpoint 
subwindow and will point to the IAR memory address if it appears in the data area 
display text. 

• Run/Stop button 

The Run/Stop button is used to start the processor/process if it is currently 
stopped, or to stop it if it is currently running. In the case of a JTAG target, a 
processor is running or stopped. In the case of a ROM Monitor or OS Open target, 
a process is running or stopped. 

Run is used to start or stop a processor/process; Stop is used to stop it. When a 
processor/process is stopped, debugger context is updated based on the current 
Instruction Pointer value for the target. If a processor/process is running, all 
controls or actions are disabled for all source level debug windows except for the 
processor/process status indicator and the Run/Stop button on the Source 
window. 

The current run/stop state of the processor/process is seen directly below this 
button in the processor/process running indicator.This is the same functionality 
which exists on the Source window (see p. 3-53). Once memory has been loaded 
with code and any applicable hardware and/or software breakpoints set, the Run 
button would be pressed to start the processor/process running. 

If the processor/process successfully starts running, the Run button will change to 
a Stop button and the processor/process running indicator will be updated to 
indicate running. The processor/process may be stopped asynchronously by 
pressing the Stop button. Doing so will change the Stop button to the Run button 
and change the processor/process running indicator. 

If, while the processor/process is running, a breakpoint is activated, or the 
processor/process stops for any reason, the Stop button will change to the Run 
button and the processor/process running indicator will be updated to indicate that 
the processor/process is stopped. The IAR field will reflect the current IAR value. 

Depending on the setting of the Track IAR check box, the data area will either 
remain unchanged (check box not selected) or will display the code at the IAR 
address (check box selected). The IAR cursor will point to the appropriate 
memory location if the check box is set or if the check box is not selected and the 
IAR is still within the address range of the displayed data. Otherwise, it will be 
removed. 

• Asm Step button 

The Asm Step button is used to single-step the processor/process to execute one 
or more 4-byte instruction values. Instruction stepping single-steps the 
processor/process starting with the instruction at the memory address referenced 
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by the IAR. Every press of the Asm Step button will execute the number of 
instructions indicated by the value in the Step count field located directly beneath 
the Asm Step button. 

• Step count 

The Step count field is used to register a new step count value. This value is used 
to determine how many instructions will be single-stepped for every press of the 
Asm Step button. To change this step count value, use the mouse to place the edit 
cursor in the step count, type in the new count value and then press Enter. The 
step count value must be entered in hexadecimal format. 

• Modifying the IAR 

The current IAR value may be modified to change the execution sequence of code 
that is being debugged using the Assembly Debug window. Use the mouse to 
place the cursor in the Set IAR field. Then type in the new IAR value and press 
ENTER. This will write the new value to the IAR and update the contents of the 
data area to reflect this new code execution point. The IAR value must be entered 
in hexadecimal format. When the IAR value is changed, the entire source level 
debugger context will be updated for the new IAR value. 

• Track IAR Check Box 

This check box is used to select the update policy used when the processor is 
stepped or is stopped after a run. When the check box is selected, the window 
contents will track the IAR setting; the data area will display the code at the IAR 
address and the IAR cursor will point to the IAR address location. If the check box 
is not selected, the data area contents will remain unchanged regardless of the 
IAR setting. The IAR cursor will move to the new address location if it is within the 
currently displayed address range; otherwise it will be removed. 


Programs Window 

The Programs window consists of a Programs subwindow with horizontal and 
vertical scrollbars, and push-buttons. 



Programs 


-> <IP> 1 /u/rwppc/examples/Dhrystone 


-1 



Hide Help 



Figure 3-6. Sample Programs Window 
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The Programs subwindow shows a list of all the programs which the debugger 
session knows about. The load command is the mechanism by which the 
debugger generates program information on the host for a particular program, and 
thus becomes ‘aware’ of the program. 

The first field for a program entry is used to indicate which program is currently 
active. A symbol will appear in this field if the program entry matches the 
program which is currently active, otherwise it will be blank. The next field for a 
program entry is used to indicate which program contains the current Instruction 
Pointer. A <IP> ‘ symbol appears in this field if the program entry matches the 
program in which the current Instruction Pointer is located, otherwise it is blank. 
The last field shows the fully qualified name of the program which was loaded. 

If the mouse is single-clicked on a program entry for a program which is not 
currently active, the debugger context will be switched to the new program, 
making it the active program. If the new program contains the Instruction Pointer, 
and the debugger is attached to the target, all appropriate source debug screens 
will be updated to reflect the context at the current Instruction Pointer. If the new 
program does not contain the Instruction Pointer, and the debugger is attached to 
the target, the Source, Locals, and Caller windows will be blanked out, and the 
Files, Functions, and Globals windows will be updated for the new program. In 
these cases, the Programs window itself will be updated to indicate the new active 
program and execution commands will still be valid. 

If the debugger is not currently attached to the target (for example, after detaching 
from a thread for an OS Open target), the Programs window is still updated to 
show the programs loaded on the host. In this case the source level debug 
screens is not functional, so single-clicking the mouse on an entry will not affect 
any source debug screens. The window can still be used to unload programs. 

If the mouse is single-clicked on a program entry for the program which is 
currently active (i.e., has the symbol next to it), the selection is highlighted and 
the Unload push-button will become enabled. The Unload push-button will unload 
the program from the host debugger, effectively making the debugger unaware of 
the programs existence, and preventing the use of any normal source level debug 
capabilities for that program. The target will not be affected by the unload. Any 
program on the Programs window can also be unloaded by double-clicking on the 
program entry. If a program has been unloaded and you wish to debug it once 
again, the load command can be used to make the debugger aware of any 
program which is still resident on the target. Refer to the load and unload 
commands in Chapter 5, "Debugger Command Reference." 

One example of the usefulness of this function is for dynamically loaded programs 
on an OS Open target. If the OS Open image and the loaded programs have any 
function calls to the other, it is possible to use the Programs window to switch 
active programs so that code and variables may be viewed at any time for each 
program. 
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It is also possible to set breakpoints in either program, if you wanted to stop in 
another program at a certain instruction, or if you inadvertently stepped into 
another program (say, at a place with no debug information) and you wanted to 
view the code in the program from which you came (and possibly set a break and 
do a run to get back to where you were previously). 

For details on how to locate specific character strings in this window, see “Input 
Line Usage” on page 3-48. 


Callers Window 

The Callers window lists the names of calling programs and functions in the 
current context. This window consists of a scrolling text window and a menu bar, 
as shown in Figure 3-7. 


Callers 


Proc_7 
Proc_3 
Proc_l 
main ; 
start 


dhry_2.c 
dhry_l.c 
dhry_l.c 


00084 

00348 

00299 


dhry_l.c ; 00163 


; start.c ; 00000 ; 
_entry ; noname ; 00000 


; 0002111C 
; 00020F54 
; 00020E08 
000207D4 ; 
00014D38 ; 
000104D4 j 


; /u/rwppc/ex 
; /u/rwppc/ex 
; /u/rwppc/ex 
/u/rwppc/exam 
/u/rwppc/exam 
/u/rwppc/exai 


Hide 


Help 


Figure 3-7. Sample Callers Window 


The information is presented essentially as a pushdown stack, with the current 
(called) function appearing as the top entry. As subsequent function calls are 
made, they then appear at the top, and the other functions are listed below. 
Similarly, as function returns are carried out, the top entry is removed, and the 
others moved up on the screen. 

Single-clicking the left mouse button over any given entry causes the debugger to 
change context to the selected (caller) function entry. The Source window shows 
the source file associated with the given function, and the source line where the 
function call was made is highlighted. Similarly, the Locals window variables are 
switched back to the variables and values valid at the time of the function call. See 
“Local Variables Window," p. 3-77 for additional information on assuring correct 
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Local variable display. This method can be repeated on all of the entries to 
traverse the entire call chain at any point in the program execution. 

Each Callers entry lists, in order, fields that indicate the function name, the source 
file containing the function, the line number of the calling instruction, the return 
address of the calling function, the program name, and the stack pointer address. 

For details on how to locate specific character strings in this window, see “Input 
Line Usage” on page 3-48. 

Files Window 

The Files window displays source filenames in the current context. This window 
consists of a menu bar and a scrolling text window, as illustrated in Figure 3-8. 


Files 


ctest,cpp 
demol,c 
demo2,c 
demo3,c 
donfs,c 
io_init. c 
panic,c 
threadO.c 
utils,c 


Hide j Help 


Figure 3-8. Sample Files Window 

The Files window lists all the source files contained in the executable currently 
loaded in the debugger. Single-clicking on any given entry causes that source file 
to appear in the Source window. The path the debugger uses to search for the file 
is dictated by the settings made using the srchpath command. 

The debugger first looks for the source file according to the path specified in the 
window. If it is not found there, the search proceeds according to any paths that 
were specified via the srchpath command. Source files can also be viewed as 
ASCII files using the File|View pulldown found on the Main window or by using the 
view command. 

For details on how to quickly locate a specific file name in this window, see “Input 
Line Usage” on page 3-48. 
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Functions Window 


The Functions window consists of a Functions subwindow with horizontal and 
vertical scrollbars, a Functions display mode selection groupbox and 
pushbuttons.The Functions subwindow displays functions for the current program. 
The format of the function entries, and which functions are displayed, depends on 
the Functions display mode setting. 

The Functions display mode groupbox consists of four radio buttons. Each radio 
button can be used to change which functions are displayed in the window (only 
those functions with symbolic debug information, or all functions in the program) 
and how they are sorted (alphabetically by name, or by ascending address). The 
Functions display mode is changed by selecting the appropriate button. The 
button which is selected indicates the current mode. 


Functions 


0x00010000; 

_entry; 

? 

0x00010558; 

putchar; 

? 

0x00010570; 

main; dhry_l.c 

0x00010D90; 

Proc_l; 

dhry_l.c 

0x00010EC4; 

Proc_2; 

dhry_l♦c 

0x00010F4C; 

Proc_3; 

dhry_l♦c 

OxOOOlOFBC; 

Proc_4; 

dhry_l.c 

0x00011020; 

Proc_5; 

dhry_l.c 

0x00011060; 

Proc_6; 

dhry_2,c 

0x00011164; 

Proc_7; 

dhry_2.c 


-Functions display mode- 1 

^ Functions w/ debug info by name 

Help 

Functions w/ debug info by addr. 

V’fill functions by name 
All functions by addr. 


Figure 3-9. Sample Functions Window 

When a mode is selected which sorts the function entries by name, each entry will 
consist of the function name, followed by an address value, followed by the name 
of the source file which contains the function. The entries will be displayed in 
alphabetical order by name. When a mode is selected which sorts the function 
entries by address, each entry will consist of an address value, followed by the 
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function name, followed by the name of the source file which contains the function. 
The entries will be displayed in order by ascending address. 

In all cases, the address value in a function entry will be the address of the start of 
the function. 

When a mode is selected which displays functions with symbolic debug 
information, only those functions for which there is symbolic debug information in 
the program will appear. Otherwise, all functions in the program will be displayed. 

A function’s entry can be selected by single-clicking the mouse on a line 
containing a functions entry within the window. If the debugger has sufficient 
information from the functions entry, the Source window will be updated to show 
the file which the function is in, with the source line corresponding to the start of 
the function appearing highlighted in the middle of the view. 

A breakpoint can be toggled by double-clicking the left mouse button on a function 
entry. A breakpoint will be toggled at the address of the start of the function (which 
is the address value in the entry). Regardless of the function mode setting, the 
Breakpoint Mode setting (selectable via the bpmode command or from the 
Breakpoints window) determines whether hardware or software breakpoint 
processing will be used. 

For details on how to quickly locate a specific function name in this window, see 
“Input Line Usage” on page 3-48. 

Load Memory Window 

The Load Memory window provides target memory write capabilities using most 
of the file formats defined for the Load command. The window is displayed by 
choosing the 'File' pulldown on the RISCWatch Main window, then selecting 
Load|Memory. 

Prior to display of the Load Memory window, a standard dialog window is 
presented to enable the user to supply the name of a file to be opened for reading. 
The dialog supplies a list of files and directories to choose from. A single left 
mouse click on a specific file, followed by the selection of the 'OK' button, will 
result in the display of the Load Memory window. 
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Figure 3-10. Load Memory 

The Load Memory window consists of the following fields: 

• File 

This field indicates the file name to be loaded. The file name can be altered by 
choosing the 'Select File’ button at the bottom of the window or by directly typing 
in the field provided. 

• File Formats 

This group box provides a list of supported file formats to choose from. See “load," 
p. 5-73 for a description of the supported file formats. Choosing a particular file 
format will result in the enabling, or disabling, of the remaining input areas of the 
window. 

• Start Address 

This field is enabled for 'Data Memory’, ’Instr Memory’, or ‘Binary’ format 
selections and indicates the initial target address to use when loading the file. This 
field must be coded if the ’Binary' format is selected. 
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Text Address 


This field is enabled for ’File’ and 'Host' format selections and indicates the initial 
target address of the instruction section of the file. This field is required when 
loading an XCOFF file and is optional when loading an ELF executable. If the ELF 
file was not compiled with relocation enabled, this field is ignored. 

• XCOFF Data Addr 

This field is enabled for ’File’ and Host’ format selections and indicates the initial 
target address of the data section of the file. This field is required when loading an 
XCOFF file and is ignored when loading an ELF executable. 

• Stack Address 

This field is enabled for ’File’ and Host’ format selections and indicates the initial 
target address of the local stack area. This is an optional field which is equivalent 
to the s=’ option provided on the Load command. Use of this field is not 
recommended since RISCWatch creates a default 16K stack area during a file 
load. In addition, most embedded applications establish their own stack area 
during initial start up code execution. 

• Stack Size 

This field is enabled for ’File’ and ’Host’ format selections and indicates the 
maximum size, in decimal, of the local stack area. This is an optional field which is 
equivalent to the ’ss=’ option provided on the Load command. Use of this field is 
not recommended since RISCWatch creates a default 16K stack area during a file 
load. In addition, most embedded applications establish their own stack area 
during initial start up code execution. 

• No Symbols/Strings 

This Check box is enabled for ’File' and ’Host’ format selections and directs 
RISCWatch not to load the additional symbol table information associated with 
boot files. See “Loading Boot and Boot Image Files” on page 3-46 for a detailed 
discussion of boot files. 

• No BSS Initialization 

This check box is enabled for ’File’ and 'Host' format selections and directs 
RISCWatch not to zero out the un-initialized data section (BSS) of the file. This 
option can significantly improve the file load performance but requires the loaded 
application to zero out the un-initialized area during program start up. Selection of 
this option is equivalent to the ’NOZERO’ option of the Load command. 

• Load 

This pushbutton is used to execute the appropriate Load command, based on the 
selections made on the window. The RISCWatch main window will indicate the 
success or failure of the operation. 
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• Select File 

This pushbutton presents a standard dialog window that allows the user to supply 
an alternate file name for loading. 

• Hide 

This pushbutton removes the Load Memory window from view. A subsequent 
display of the Load Memory window will present the field settings that were in 
existence when the 'Hide' button was pressed. 

• Help 

This pushbutton will present any available help topic for this window. 


OS Open Debugging 

The OS Open window is used to display operating system construct information 
and control debug attachment for an IBM OS Open Real-time Operating system 
program image. The OS Open window is available only if OS Open is specified as 
the target in the RISCWatch environment file. 



Figure 3-11. Sample OS Open Window 


The OS Open window consists of a subwindow with horizontal and vertical 
scrollbars and a number of push-buttons used to dynamically load a file, 
start/kiIl/detach an OS Open thread, and display OS Open construct information. 
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The subwindow displays information relevant to the construct display push-button 
which was last selected. For some constructs, single-clicking the mouse on a list 
entry will display more specific information immediately under the entry, or will 
contract this information if it is already displayed. There will be a message at the 
top of the display window if the expansion/ contraction function is available for the 
current display. 

Note: In general, the contents of the subwindow will not be automatically updated 
as the application runs on the target. In each case, when a display pushbutton is 
selected, or a single-click is performed for a construct which supports it, the latest 
information for the entire window will be retrieved from the target and displayed. 

For details on how to locate specific character strings in this window, see “Input 
Line Usage” on page 3-48. 

Following are descriptions of the pushbuttons in the OS Open window: 

• Load Module button 

This pushbutton brings up the Load Module window. Entering the name of a file 
which is located on a file system mounted on the target OS Open system causes 
that file to be dynamically loaded by OS Open into the target. Also, the file to be 
loaded must be located in the current RISCWatch search path. A thread 
corresponding to the entry point for the program loaded will be queued. A 
breakpoint will be put at this entry point and the debugger will be initialized to 
debug this thread. 

Note: for OS Open systems with Virtual Memory support: Unless otherwise 
specified, newly loaded modules will be loaded into a new thread group. To 
specify an existing thread group, use the load file command’s tg parameter. 

For example, to load module /fat/cat.ld into thread group 0x5435770, type: 

/fat/cat.ld tg=0x5435770 

• Start Thread button 

This pushbutton brings up the Start Thread window. Entering a function name 
which is part of the target program image will initialize a source mode debug 
session with OS Open. 

A thread corresponding to the specified function will be queued, with a breakpoint 
set at the entry of the function. 
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Notes: 

RISCWatch cannot be used to debug the OS Open shell. 

For OS Open systems with Virtual Memory support: Unless otherwise 
specified, newly started threads will be started in a new thread group. To 
specify an existing thread group, specify the thread group id after the function 
name. For example, to start the thread my_hello_world in thread group 
0x5435701,type: 

my_hello_world 0x5435701 

• Detach Thread button 

This pushbutton ends the source mode debug session with OS Open by 
disconnecting from the thread which is currently being debugged. The thread will 
continue to run normally on the target. 

• Kill Thread button 

This pushbutton ends the source mode debug session with OS Open by 
destroying the thread which is currently being debugged. 

• Threads button 

This pushbutton lists each thread in the OS Open system in the display 
subwindow. If a thread is currently being debugged, a ‘D’ will appear in the first 
column of the list entry. If the mouse is double-clicked on a thread list entry, the 
thread will be attached if it is not already being debugged, or detached if it is 
currently being debugged. 

Note: RISCWatch cannot be used to debug the OS Open shell. 

If the mouse is single-clicked on a list entry which is not already expanded, the 
window display will be expanded to show detailed information about that specific 
thread directly below the thread list entry. If the mouse is single-clicked on a list 
entry which is already expanded, the detail for that list entry will be contracted. 

• Mutexes button 

This push-button lists each mutex in the OS Open system in the display 
subwindow. If the mouse is single-clicked on a list entry which is not already 
expanded, the window display will be expanded to show detailed information 
about that specific mutex directly below the mutex list entry. If the mouse is 
single-clicked on a list entry which is already expanded, the detail for that list entry 
will be contracted. 

• Condition Variables button 

This pushbutton lists each condition variable in the OS Open system in the display 
subwindow. If the mouse is single-clicked on a list entry which is not already 
expanded, the window display will be expanded to show detailed information 
about that specific condition variable directly below the condition variable list entry. 
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If the mouse is single-clicked on a list entry which is already expanded, the detail 
for that list entry will be contracted. 

• Semaphores button 

This pushbutton lists each semaphore in the OS Open system in the display 
subwindow. If the mouse is single-clicked on a list entry which is not already 
expanded, the window display will be expanded to show detailed information 
about that specific semaphore directly below the semaphore list entry. If the 
mouse is single-clicked on a list entry which is already expanded, the detail for 
that list entry will be contracted. 

• Timers button 

This pushbutton lists each timer in the OS Open system in the display subwindow. 

If the mouse is single-clicked on a list entry which is not already expanded, the 
window display will be expanded to show detailed information about that specific 
timer directly below the timer list entry. If the mouse is single-clicked on a list entry 
which is already expanded, the detail for that list entry will be contracted. 

• Message Queues button 

This pushbutton lists each message queue in the OS Open system in the display 
subwindow. If the mouse is single-clicked on a list entry which is not already 
expanded, the window display will be expanded to show detailed information 
about that specific message queue directly below the message queue list entry. If 
the mouse is single-clicked on a list entry which is already expanded, the detail for 
that list entry will be contracted. 

• Memory Pools button 

This pushbutton lists each memory pool in the OS Open system in the display 
subwindow. 

• Heaps button 

This pushbutton lists each heap in the OS Open system in the display subwindow. 

• FLIHs button 

This pushbutton lists each first level interrupt handler in the OS Open system in 
the display subwindow. 

• Signals button 

This pushbutton lists each signal in the OS Open system in the display 
subwindow. 

• Libraries button 

This pushbutton lists each registered library in OS Open system in the display 
subwindow. 
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• Thread Group List button 

This pushbutton is only available if the target is an OS Open system with Virtual 
Memory support. It will list each thread group in the OS Open system in the 
display subwindow. 

If the mouse is single-clicked on a list entry which is not already expanded, the 
window display will be expanded to show detailed information about that specific 
thread group directly below the thread group list entry. If the mouse is single¬ 
clicked on a list entry which is already expanded, the detail for that list entry will be 
contracted. 

• Hide button 

This pushbutton hides the window. 

• Help button 

This push-button accesses the on-line RISCWatch User’s Guide. 

For more information on the OS Open Real-Time Operating System, refer to 
“Related IBM Publications” on page xxiv. 


Managing Breakpoints 

Breakpoints within RISCWatch fall into two categories: 

• Software breakpoints 

• Hardware breakpoints 

Software breakpoints are implemented by replacing the instruction at the 
breakpoint address with a trap instruction. Hardware breakpoints make use of the 
debugging features designed into specific PowerPC processors. When the 
processor/process stops, all the trap instructions are replaced with the original 
instructions residing at the breakpoint addresses. 

Notes: 

For PowerPC 6xx/7xx processors connected via a JTAG target, hardware 
breakpoints cannot be used if software breakpoints are set and, conversely, 
software breakpoints cannot be used if hardware breakpoints are set. 

Hardware breakpoints are not available on OS Open targets. 
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Using Software Breakpoints 

• Setting Software Breakpoints from the RISCWatch Debugger Windows 

Software breakpoints can be set or cleared in a number of ways using the 
RISCWatch Debugger windows. Note that the Breakpoint Mode must be set to 
Software mode (see bpmode on page 5-24). 

1. Source window 

Software breakpoints can be set and cleared in the Source window (Figure 
3-4) by moving the cursor to the targeted source line and then single-clicking 
the left mouse button on the line corresponding to the targeted source line in 
the Status window, left of the source lines. An indicator will appear next to the 
line number of the target source line. Similarly, an existing breakpoint can be 
cleared by single-clicking on the line. The single-clicking toggles the break¬ 
point setting for a target source line. 

If in mixed/source and assembly mode, the breakpoints can be set and 
cleared the same way, with the target line in this case being an assembly 
instruction instead. 

2. Breakpoints window 

Software breakpoints can be viewed and cleared from the Breakpoints win¬ 
dow (Figure 3-12). Double-clicking on an entry will clear the breakpoint. Sin¬ 
gle-clicking on an entry will highlight the entry and enable clearing by then 
pressing the Delete button. The Delete All button can be used to delete all 
current breakpoints. 

3. Assembly Debug window 

Software breakpoints can be set and cleared from the Assembly Debug win¬ 
dow (Figure 3-47) by single-clicking on the buttons along the left side of the 
disassembly entries. This action also toggles the breakpoint each time it is 
performed. 

4. Functions window 

Software breakpoints can be set and cleared from the Functions window (Fig¬ 
ure 3-9) by double-clicking the left mouse button on a function entry. A break¬ 
point will be toggled at the address of the start of the function. 
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• Setting Software Breakpoints with the bp Command 

To set a software breakpoint, you can use a bp command along with the address 
of the instruction to stop at and RISCWatch takes care of the rest. For example, to 
stop just prior to the execution of the instruction at address 0xFFFC0004, issue 
the following command: 

bp set 0xFFFC0004 

The processor/process could then be started using the run command. If the 
processor/process were to try and execute the instruction at this address, the 
processor/process would stop and an event would be generated which 
RISCWatch would detect. It would then be possible to examine the state of the 
processor. 

To clear this software breakpoint, simply issue the command 
bp clear 0xFFFC0004 

See bp on page 5-20 in the Command Reference for a detailed description of 
available functionality. 

Using Hardware Breakpoints 

• Setting Hardware Breakpoints from the RISCWatch Debugger Windows 

Flardware breakpoints can be set or cleared in a number of ways using the 
RISCWatch Debugger windows. Note that the Breakpoint Mode must be set to 
Flardware mode (see bpmode on page 5-24). 

1. Source window 

Flardware breakpoints can be set and cleared in the Source window only 
when the source screen is in mixed source/assembly mode. Single-clicking 
the left mouse button on the line corresponding to the targeted assembly 
instruction in the Status window, left of the assembly instructions, will alter¬ 
nately set and clear the breakpoint. An indicator will appear next to the target 
line in the line number field when the breakpoint is set. 

2. Breakpoints window 

Flardware breakpoints can be viewed and cleared from the Breakpoints win¬ 
dow. Double-clicking on an entry will clear the breakpoint. Single-clicking on 
an entry will highlight the entry and enable clearing by then pressing the 
Delete button. The Delete All button can be used to delete all current break¬ 
points. 

3. Assembly Debug window 

Flardware breakpoints can be set and cleared from the Assembly Debug win¬ 
dow by single-clicking on the buttons along the left side of the disassembly 
entries. This action also toggles the breakpoint each time it is performed. 
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Figure 3-12. Sample Breakpoints Window 


4. Functions window 

Hardware breakpoints can be set and cleared from the Functions window by 
double-clicking the left mouse button on a function entry. A breakpoint will be 
toggled at the address of the start of the function. 


• Setting Hardware Breakpoints with the bp Command 

RISCWatch allows access to the available hardware registers used to control 
breakpoints through the use of the bp command. This type of access allows for 
the usage of native processor debugging facilities to control when a running 
processor will be stopped. This access is dependent on the processor being used 
and the available functionality may vary. 

“Trigger/Trace Window (400Series Only)” on page 4-7 and “Compound 
Trigger/Trace Window (401,403 Series Only)” on page 4-12 provide descriptions 
of other (processor-specific) windows for handling hardware breakpoints. 


Breakpoints Window 

The Breakpoints window consists of a Breakpoint subwindow with horizontal and 
vertical scrollbars, a Breakpoint Mode selection groupbox, and push-buttons. The 
Breakpoint subwindow displays any breakpoints that are currently set. 
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The Breakpoint entry contains information about the breakpoint, with each field 
separated by a semicolon. If the entry is for an Instruction breakpoint, the first field 
contains the letter ‘H’ or ‘S’ to indicate a Hardware or Software breakpoint, 
respectively. The next fields in order show the address of the breakpoint, the 
function containing the breakpoint, the file containing the breakpoint, the line 
number in the file which the breakpoint is set at, and the program which the 
breakpoint is set in. If the values of any of the fields cannot be determined by the 
debugger they will be designated by values of zero in the case of numbers and '?' 
in the case of strings. 

If the entry is for a Data breakpoint, the first field contains the letter ‘D’. The next 
fields in order show the Data Address Compare value, the Data Address Compare 
register used, the Data Address Compare Write/Read enable, and the Data 
Address Compare size. 

Breakpoints may be set or deleted in several ways during a debug session. In 
each case, the Breakpoints window will be automatically updated to reflect the 
currently set breakpoints. 

A breakpoint can be selected by single-clicking the mouse on a line containing a 
breakpoint entry within the window. This will cause the breakpoint entry to 
become highlighted. For an Instruction breakpoint, if the debugger has sufficient 
information from the breakpoint entry, the Source window will be updated to show 
the source file in which the breakpoint is set, with the source line which the 
breakpoint is set at appearing highlighted in the middle of the view. No attempt will 
be made to update the Source window for a breakpoint with an unknown program 
(program field is The Assembly Debug window will also be updated when an 
Instruction breakpoint entry is selected to display memory starting at the address 
of the breakpoint. Single-clicking on an already selected breakpoint entry will 
deselect it. 

The Delete pushbutton is disabled unless a breakpoint entry is selected, at which 
time it is enabled. Pressing the Delete pushbutton will cause the selected 
breakpoint to be deleted. A breakpoint can also be deleted by double-clicking on 
the breakpoint entry. When an Instruction breakpoint is deleted, the Breakpoints 
window and the Status subwindow in the Source window will reflect the current 
status. 

The Delete All pushbutton will delete all current breakpoints. 

The Breakpoint Mode groupbox consists of three buttons: Software BPs, 
Hardware BPs, and HardStep BPs. The Breakpoint mode is changed by selecting 
the appropriate button. The button which is on indicates the current mode. 

When in Software mode, breakpoints are set by writing trap instructions in place 
of program instructions. 
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When in Hardware mode, user designated breakpoints are set via the hardware 
debug registers of the target processor. RISCWatch breakpoints used for line 
stepping and call stepping are applied as software breakpoints. 

In HardStep mode, all breakpoints are applied using the hardware debug registers 
of the target processor. When performing line steps or call steps, a single 
hardware debug register (highest number IAC/IABR register) is used to run to the 
next source line or function. In addition, if a breakpoint is applied when all 
processor resources are in use, a previously applied breakpoint (contained in the 
highest numbered IAC/IABR) is automatically removed and the new breakpoint 
applied.HardStep mode is useful when debugging code resident in read only 
memory, where software traps can not be written. 

There are a finite number of hardware breakpoints available. The number is 
based on the target processor and is dependent on how many hardware debug 
registers it has. Error messages will be generated if attempts are made to set 
Hardware breakpoints in Hardware mode and none are available. 

If the mouse is single-clicked on an Instruction breakpoint entry which 
corresponds to a program which is currently not active, the debugger context will 
be switched for the new program, making it the active program. If the new program 
contains the Instruction Pointer, all appropriate source debug screens will be 
updated to reflect the context at the current Instruction Pointer. If the new program 
does not contain the Instruction Pointer, the Source, Locals, and Caller windows 
will be blanked out, and the Files, Functions, and Globals windows will be updated 
for the new program. Refer to the Programs window description for more 
information on debugging with multiple programs simultaneously. 

The RISCWatch Debugger also uses the bp command to manage both types of 
breakpoints. See bp on page 5-20 for further details. 

See “Compound Trigger/Trace Window (401,403 Series Only)” on page 4-12 and 
“Compound Trigger/Trace Window (401,403 Series Only)” on page 4-12 for 
additional RISCWatch debugging windows that manage PowerPC 400Series 
hardware breakpoints. 

Breakpoint Select Window 

The Breakpoint Select window appears when an attempt is made to set or delete 
a breakpoint with the mouse on a source line in the Source window, and that 
source line corresponds to multiple functions in the program. An example of when 
this situation could exist is when debugging source code containing C++ 
templates. The Breakpoint Select window can then be used to set or remove 
breakpoints for particular functions associated with the selected source line. 
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Breakpoint Select 



BP Set 


BP Not Set 


LULDARRAY <SOFT_INST_BRKPT>::Append( 
LULDARRAY<DATA_BRKPT>::Append(const 
LULDARRAY<HARD_INST_BRKPT>::Append( 


LULDARRAY<LW_STRING>::Append(const 
LW_DARRAY<STM*>::Append(STM* consta 
LUI_DARRAY<DBG_BP_INFO>:: Append (cons 
LULDARRAY<DBG_PGM_GLOBAL_VAR>::Appe 
LULDARRAY <DBG_PGM_LOCAL_VAR>::Appen 
LULDARRAY <DBG_PGM_FILE*>::Append(DB 
LW_DARRAY <DBG_PGM_VAR>::Append < cons 
LULDARRAY <DBG_PGM_ENUM>::Append(con 
LULDARRAY <DBG_PGM_STRUCT_UNION>::Ap 
LULDARRAY <DBG_PGM_VAR_RANGE>::Appen 
LULDARRAY <DBG_PGM_TAG>::Append(cons 
LULDARRAY<RUI_INTX>:: Append (const RW. 
LUI_DARRAY<unsigned long>:: Append(co 


Move all to EP Set Move all to BP Not Set OK Cancel 

Figure 3-13. Sample Breakpoint Select Window 


Help 


The window consists of a BP Set subwindow with horizontal and vertical 
scrollbars, a BP Not Set subwindow with horizontal and vertical scrollbars, and 
push-buttons. 

The BP Set and BP Not Set subwindows are used to select the functions for which 
breakpoints related to the chosen source line will be set. If breakpoints are 
currently set for an associated function, its name will initially appear in the BP Set 
window. If breakpoints are not currently set for an associated function, its name 
will initially appear in the BP Not Set window. 

Single clicking the mouse on a function in one of the subwindows will move it to 
the other subwindow. The Move All to BP Set push-button will move all the 
functions to the BP Set subwindow. The Move All to BP Not Set push-button will 
move all the variables to the BP Not Set subwindow. 

If the information on the Breakpoint Select is applied via the OK pushbutton, the 
appropriate breakpoints for the selected source line will be set for each function 
currently listed on the BP Set subwindow. Also, associated breakpoints will be 
removed if a function is in the BP Not Set subwindow at the time the changes are 
applied and it initially had breakpoints set. The Cancel pushbutton is used to 
close the window without applying any changes. 


3-76 


RISCWatch Debugger User's Guide 




Reading and Writing Program Variables 

Many methods of updating and viewing program data are provided by the 
RISCWatch Debugger. They can be used by themselves or in concert with others 
to provide a wide range of options on how data is presented. 

The Locals and Globals windows display selected local and global variables, 
respectively, for the program currently being debugged.The Variable Configuration 
window can be selected from the Locals or Globals window to configure variable 
information for all Local or Global variables. In addition, the Change Variable 
window can be used to alter an individual variable’s value, type, or display 
information. The following sections describe the capabilities of each of these 
windows. 

Local Variables Window 

The Locals window displays local variables in the current source file. Figure 3-14 
shows an example of a Locals window. 



Figure 3-14. Sample Locals Window 

The Locals window consists of a Locals subwindow with horizontal and vertical 
scrollbars and push-buttons. The Locals subwindow displays the visible local 
variables for a function. The variables which can be displayed are dependent on 
the current local variable context for the debugger. Variables can be shown which 
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correspond to the current instruction context, that is, variables for the function 
associated with the current Instruction Pointer address. These are automatically 
shown after performing an execution command like run or linestep. 

Variables can also be shown which correspond to a previous function in the call 
chain. The Callers window is used to select the context of a function on the callers 
stack, and the Locals window will be updated appropriately. Variables displayed in 
the Locals Screen may have an address indicating a processor register. Proper 
display of a calling function’s register variable (selecting a back level entry on the 
Callers Screen) requires the existence of a tag word section in the executable. In 
the absence of a “.tags” section, the Caller’s register variable value is assumed to 
be in the register save area of the called function, which will not always be correct. 
By using the -Hoff=debugger_handles_reg_vars High C/C++ compile option, you 
can disable local register assignments. All locals will be assigned to memory 
locations and proper display of all the caller’s variables will be guaranteed. 

A local variable entry consists of the variable name followed by configurable 
variable information. Configurable variable information includes the value of the 
variable (if it is a fundamental type) expressed in a format selectable by the user, 
the variable type enclosed in a left/right arrow pair (<>), the address of the 
variable preceded by an ‘at’ sign (@), and the size of the variable enclosed in 
parentheses. The Variable Configuration and Change Variable windows are used 
to configure the variable information for the local variables. 

If the address for a variable is not a valid memory address for the target being 
debugged, the words ‘INVALID VALUE’ will appear in place of a numeric value as 
long as the address is invalid. The address field will show the current address 
associated with the variable. Variable detail and format changes can still be 
applied while the variable is in this state, and will be applied if during the course of 
debugging the program the variable address becomes valid. 

For example, if an un-initialized pointer is defined, the contents of this pointer may 
initially be outside the range of valid memory for the target, in which case any data 
element pointed to by the pointer would have an invalid value. As soon as the 
pointer is assigned a valid value for the program, say, by a call to malloc(), the 
data elements pointed to should then contain valid data. 

Single-clicking the left mouse button on a variable entry selects the variable and 
opens the Change Variable window appropriate for the type of the selected 
variable (integer, structure, and so on). The Change Variable window is used to 
configure variable information for an individual variable. See “Change Variable 
Window," p. 3-85. 

Double-clicking the left mouse button on a structure, pointer, or union variable 
entry expands the variable detail one level if it is expandable and it has not already 
been fully expanded. You can continue to expand the variable detail another level 
by continuing to double-click on the variable entry. 
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Double-clicking the right mouse button on a structure, pointer, or union variable 
entry contracts the variable detail to the point which was clicked on. Subsequent 
expansion of the variable at this point will result in the variable being expanded to 
the level of detail which it was at when it was contracted. 

The Variable Config push-button is used to open the Variable Configuration 
window. The Variable Configuration window, when opened from the Locals 
window, is used to configure variable information for all the local variables in the 
current locals context. See “Variable Configuration Window," p. 3-83. The Read 
push-button is used to manually force a read of the values of the variables which 
are displayed on the Locals window from the target. 

Note: “Input Line Usage” on page 3-48 describes shortcut key operations for 
performing character string searches on this window. 

Global Variables Window 

The Globals window consists of a Globals subwindow with horizontal and vertical 
scrollbars and push-buttons. 

The Globals subwindow displays the visible global variables for the program 
currently being debugged. For performance reasons, when a program is initially 
loaded, all global variables are set up to be invisible. The Var. Config button must 
be used to make them visible. A global variable entry consists of the file which the 
variable is in, followed by the variable name and configurable variable information. 
Configurable variable information includes the value of the variable (if it is a 
fundamental type) expressed in a format selectable by the user, the variable type 
enclosed in a left/right arrow pair (<>), the address of the variable preceded by an 
‘at’ sign (@), and the size of the variable enclosed in parentheses. The Variable 
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Configuration and Change Variable windows are used to configure the variable 
information for the global variables. 



Figure 3-15. Sample Globals Window 


If the address for a variable is not a valid memory address for the target being 
debugged, the words ‘INVALID VALUE’ will appear in place of a numeric value as 
long as the address is invalid. The address field will show the current address 
associated with the variable. Variable detail and format changes can still be 
applied while the variable is in this state, and will be applied if during the course of 
debugging the program the variable address becomes valid. 

For example, if an un-initialized pointer is defined, the contents of this pointer may 
initially be outside the range of valid memory for the target, in which case any data 
element pointed to by the pointer would have an invalid value. As soon as the 
pointer is assigned a valid value for the program, say, by a call to malloc(), the 
data elements pointed to should then contain valid data. 

Single-clicking the left mouse button on a variable entry will select the variable 
and open the Change Variable window appropriate for the type of the selected 
variable (integer, structure etc.). The Change Variable window is used to configure 
variable information for an individual variable. Refer to the Change Variable 
window description. 

Double-clicking the left mouse button on a structure, pointer, or union variable 
entry will expand the variable detail one level if it is expandable and it has not 
already been fully expanded. You can continue to expand the variable detail 
another level by continuing to double-click on the variable entry. 
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Double-clicking the right mouse button on a structure, pointer, or union variable 
entry contracts the variable detail to the point which was clicked on. Subsequent 
expansion of the variable at this point will result in the variable being expanded to 
the level of detail which it was at when it was contracted. 

The Variable Config push-button is used to open the Variable Configuration 
window. The Variable Configuration window, when opened from the Globals 
window, is used to configure variable information for all the global variables in the 
program. See “Variable Configuration Window," p. 3-83. The Variable Config 
push-button will be disabled if there is no source debug information for the current 
program. 

The Read push-button is used to manually read the values of the variables which 
are displayed on the Globals window from the target. 

Note: “Input Line Usage” on page 3-48 describes shortcut key operations for 
performing character string searches on this window. 

Inspect Variable Windows 

An Inspect window consists of a variable subwindow with horizontal and vertical 
scrollbars and push-buttons. 

Inspect variable windows are used to display and change variable contents and 
display information in much the same manner as the Local and Global Variable 
windows. However, the Inspect window contains only one variable per window, 
and it can be either a local or a global variable. Multiple windows are allowed, and 
are identified by a colon and instance number, along with the variable name. 
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Figure 3-16. Sample Inspect Window 

Inspect windows can be created via the GUI interface using the Source window or 
by command line using the window command. To invoke an Inspect window via 
the Source screen, the user simply clicks and holds the right mouse button over 
the variable to be inspected. A menu list will appear that includes an Inspect 
selection. When selected, a new window is created for that particular variable 
only. The ability to have multiple copies of the same variable is also supported. 

Single-clicking the left mouse button on the variable entry will open the Change 
Variable window appropriate for the type of the selected variable (integer, 
structure etc.). The Change Variable window is used to configure variable 
information for an individual variable. Refer to the Change Variable window 
description. 

Double-clicking the left mouse button on a structure, pointer, or union variable 
entry will expand the variable detail one level if it is expandable and it has not 
already been fully expanded. You can continue to expand the variable detail 
another level by continuing to double-click on the variable entry. 

Double-clicking the right mouse button on a structure, pointer, or union variable 
entry contracts the variable detail to the point which was clicked on. Subsequent 
expansion of the variable at this point will result in the variable being expanded to 
the level of detail which it was at when it was contracted. 
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Variable Configuration Window 

The Variable Configuration window is used to change variable information for all 
local or global variables. It consists of a Display Information selection groupbox, a 
Compiler-created Variable selection groupbox, a Visible subwindow with 
horizontal and vertical scrollbars, a Not Visible subwindow with horizontal and 
vertical scrollbars, and push-buttons. 


Variable Configuration 




Read info* 
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_l Show Size 
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_J Use Block Read 
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QHide 
: w ) Show 
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Figure 3-17. Sample Variable Configuration Window 


The Variable Configuration window is opened via the Variable Configuration 
push-button on the Locals or Globals window. The OK push-button is used to 
apply the selected information to the associated variable window (the variable 
window from which the Variable Configuration window was opened). The Cancel 
push-button is used to close the window without applying any changes. 

The Variable Configuration window is intended to be used for applying 
configuration changes to a variable window once it is opened. The Variable 
Configuration window will be brought down without any changes being applied if it 
is open and the associated variable window is brought down or updated. An 
existing Variable Configuration window will also be brought down with no changes 
applied if another Variable Configuration window or a Change Variable window is 
opened while the Variable Configuration window is up. 

The Display Information groupbox consists of four check boxes. The first 3 check 
boxes enable display of the Address, Size and Type information. The ‘Use Block 
Read’ check box is available to improve variable read performance by performing 
block reads of structures and array elements. The initial state of the check boxes 
shows the currently enabled default display information for the associated local or 
global variable window. If the information on the Variable Configuration window is 
applied, each variable entry on the variable window will be updated to reflect the 
selected display information. The display changes will be applied to any variable 
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actively using the ‘Use Defaults’ read information setting. This setting can be 
displayed or altered on the Change Variable window. 

The Compiler-created variable groupbox consists of three buttons, one to hide 
variables which are created by the compiler, one to show variables which are 
created by the compiler, and one to leave the current setting. The debugger keys 

off variables beginning with two underscores ('_') to determine variables created 

by the compiler. They are typically present in C++ programs. The initial state is to 
have the compiler-created variables hidden. Selecting the Hide button will move 
all variables beginning with two underscores to the Not Visible subwindow. 
Conversely, selecting the Show button will move all variables beginning with two 
underscores to the Visible subwindow. 

The Visible and Not Visible subwindows are used to select which variables will be 
visible on the associated variable window. No processing is done for a variable 
while it is not visible. All local variables are initially visible. All global variables are 
initially not visible. 

Single-clicking the mouse on a variable in one of the subwindows will move it to 
the other subwindow. The Move All to Vis push-button will move all the variables 
to the Visible subwindow. The Move All to Invis push-button will move all the 
variables to the Not Visible subwindow. If the information on the Variable 
Configuration window is applied, a variable entry will appear on the associated 
variable window for each variable in the Visible subwindow. 

Note: For local variables, all variables defined for the function will be shown, 
regardless of whether they are currently in scope. If multiple instances of variables 
with the same name are defined with different scope within a function, the variable 
name will appear repeated times in the window. Each variable instance on the 
window will correspond to a variable definition within the function. 

Note: “Input Line Usage” on page 3-48 describes shortcut key operations for 
performing character string searches on this window. 
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Change Variable Window 
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Figure 3-18. Change Variable Window 

The Change Variable window is used to change variable information for an 
individual local or global variable. This window is opened by single-clicking the 
mouse on an individual line entry in the Locals or Globals window. The type of 
variable selected determines which format options are enabled when the window 
is displayed. Variable types are classified as Base (int, char, enum, etc), Array, 
Pointer, Structure or Union. The following information describes the fields 
displayed in the Change Variable window. 

• Variable Name 

The Variable Name field contains the name of the variable chosen. In addition, the 
field title area indicates the associated variable window (local or global) and the 
current type (Array, Pointer, Base, or Struct/Union) assigned to the variable. 
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• Display Information 

The Display Information groupbox consists of three check boxes to enable display 
of Address, Size and Type information for the selected variable on the associated 
variable window. The ‘Use Block Read’ check box is used to improve performance 
by executing memory block reads on structures and array elements. The ‘Use 
Defaults’ check box informs RISCWatch to use the default settings made on the 
Variable Configuration window. 

The initial state of the check boxes shows the currently active display information 
for the associated variable. If the information on the Change Variable window is 
applied, the variable entry on the associated variable window will be updated to 
reflect the selected display information. The display changes will be applied to any 
portions of the variable which were ‘revealed’ or expanded, whether they are 
currently visible or not. 

• Variable Detail 

The Variable Detail groupbox consists of three check boxes: ‘More detail’, ‘Less 
detail’, and ‘Leave detail’. ‘Leave detail’ will always be the default when the 
window comes up. Selecting ‘More detail’ will expand the variable to the next level 
of expansion, if it can be expanded further. If the variable was previously 
expanded multiple levels from that point, those levels of expansion will be shown 
as well. Selecting ‘Less detail’ will contract the variable detail to the level of the 
selected variable. The detail changes will only take effect if the changes for the 
window are applied. Refer to “Expansion/Contraction from Locals or Globals 
Window” on page 3-88 for more discussion on changing the level of detail for a 
variable. Note that base variables, such as ‘longs’ or ‘ints’, have no additional 
detail to display, so the ‘More detail’ and ‘Less detail’ selections are disabled. 

• Value Format 

The Value Format groupbox consists of a number of buttons used to change the 
format of the selected variable. For example, if the value of the selected variable is 
displayed as decimal 12 on the Locals window, it will be displayed as 
'OxOOOOOOOC' if the Flexadecimal format is applied. The following formats are 
supported: “Show as Array” and ‘Show as Ptr’ (valid for Pointer types only), ASCII, 
‘ASCII string’ (for base char types), Binary, Cast, Flexadecimal, Octal, Signed, 
Unsigned, and Default. Default is the format which RISCWatch has defined for 
each fundamental type. See “Formatting Examples," p. 3-88, for specific details on 
Type Casting, ASCII string display, and other formatting options. 

• Change Value 

The Change Value field is used to change the value of the variable. Values can be 
entered in decimal or hexadecimal notation. If an invalid value is entered, an error 
message will be displayed in the Main window and the Change Variable window 
will remain visible to accept another entry. When applied, the variable value will be 
written to the target and the variable entry on the associated variable will be 
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updated to reflect the new value. The Change Value Field does not exist if the 
Cast or ‘Show as Array’ Value Format selections are chosen. In addition, ‘Array’ 
and ‘Struct/Union’ variable types do not contain the Change Value field (a value is 
only meaningful when referring to a specific member or element of these types). 

• Change Array Subrange 

The Change Subrange field is used to change the number of elements displayed 
for either an array variable or a pointer variable (when ‘Show as Array’ Value 
Format is used). It is initialized with the current subrange value. The limits of the 
array will be shown in the title above the change field. The low and high subrange 
values should be separated by a comma with no spaces. If an invalid subrange is 
entered, an error message will be displayed in the Main window and the Change 
Variable window will remain up to accept another entry. If a subrange value is 
entered which is outside the limits for the array, a warning message is displayed 
and the entered value is used. When applied, the array variable will be expanded 
on the associated variable window to show the array elements for the entered 
subrange. 

• Enter Type 

The Enter Type field is used to change the type (Type Cast) of the selected 
variable. This field is activated when the Cast Value Format is selected. A valid 
‘type name’, followed by any number of ’*’s to indicate pointer indirection, must be 
entered. Valid ‘type names’ include fundamental ’C’ types such as ’int’, ’long’, 
'signed char’, etc... In addition, any user defined 'type name’ (i.e. structures 
defined in your ’C’ code) can be used. Using the name ‘#default’ will restore the 
variable's type to the original compiler setting. 

The ‘type name’ may also be preceded by an optional file name (with or without 
single quotes), followed by a colon (i.e. file.c:structa* or ‘file.c’:structa*), to direct 
RISCWatch to search the debug information of a specific source file. In the 
absence of a file identifier, RISCWatch will only search for a name match in the 
source file where the variable was originally defined. 

Refer to “Type Casting a Variable” on page 3-102 for additional information. 

• Apply To Each Var. Instance 

A check box titled ‘Apply to each var. instance at this level’ will appear above the 
buttons at the bottom of the window if the selected variable is part of an array 
element (and more than one element exists for the array from the perspective of 
the debugger). If it is selected when changes are applied for the window, they will 
be applied to each instance of the variable within multiple elements of the array. 
Refer to “Changing Multiple Instances of a Variable Within an Array” on page 3-94 
for a detailed description of this support. 
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• OK 

The OK push-button is used to apply the selected information to the associated 
window (Locals or Globals) for the variable selected. If an invalid value is 
detected, the Change Variable window will remain visible and an error message 
will be displayed in the RISCWatch Main status window. 

• Cancel 

The Cancel push-button is used to close the window without applying any 
changes. 

• Help 

The Help push-button is used to display any available help topic for this window. 

Formatting Examples 

This section contains examples on how to manipulate the variable information 
which is displayed on the Locals or Globals variable window: 

Expansion/Contraction from Locals or Globals Window 

Consider the following (unexpanded) structure variable entry on a Locals or 
Globals variable window: 


show_out: <struct Struct_Outer> 

Figure 3-19. Sample Unexpanded Structure Variable 

Double-clicking the left mouse button on this variable line will result in expanding 
the structure to show the individual elements: 


show_out: <struct Struct_Outer> 

♦show_in: <struct inside> 
♦variant: <union> 

Figure 3-20. Sample Expanded Structure Variable 
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Double-clicking the left mouse button again on the same line will continue to 
expand by one level each data element of the structure: 


show_out: <struct Struct_Outer> 

.show_in: <struct inside> 

.count: +928 <int> 

.name: <arrayC10] of char> 
.variant: <union> 

.var_l: <struct> 

♦var_2: <struct> 

♦var_3: <struct> 


Figure 3-21. Further Structure Variable Expansion 


Note that we could have chosen above to only expand one of the data elements of 
the structure by moving the mouse to that specific element (.showjn, say) and 
double-clicking the left mouse button on it. We can demonstrate this ability to 
expand an individual element by now double-clicking the left mouse button on the 
(now visible) name array element of the nested .showjn structure: 


show_out: <struct Struct_Outer> 

.show_in: <struct inside> 

.count: +928 <int> 

.name: <arrayC10] of char> 
[OH: '\x0' <char> 

[1]: '\x2' <char> 

[2D: <char> 

.variant: <union> 

.var_l: <struct> 

.var_2: <struct> 

*var_3: <struct> 

Figure 3-22. Single-Element Structure Variable Expansion 

Note that in this case the expansion took place from the line which was 
double-clicked on. Also, because this was an array and not a structure, the 
elements are listed by array index. In this case, only the first three elements of the 
array were shown when it was expanded, which is the default setting for arrays 
with three or more elements. The subrange to view for an array can be changed 
via the Change Variable window which is opened by single-clicking the left mouse 
button on the array variable entry. (See p. 3-85.) 
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Now, we can demonstrate the ability to contract variable elements by 
double-clicking the right mouse button on the .showjn element. This will contract 
the variable information displayed up to this element. 


show_out: <struct Struct_Outer> 

.show_in: <struct inside> 
.variant: <union> 

.var_l: <struct> 
.var_2: <struct> 
.var_3: <struct> 


Figure 3-23. Structure Variable Contraction 

The next time the .showjn element is expanded, it will be expanded to the level of 
detail to which it was previously expanded above. 

Using these techniques, variables consisting of complex data elements can be 
customized to show various levels of detail for each data element comprising the 
variable. 

Displaying ASCII Strings 

Consider the following variable which is a pointer to type char on a Locals or 
Globals variable window: 


Str_l_Par_Ref: 0x0002E248 <ptr to char> 


Figure 3-24. Sample Pointer Variable 

Single-clicking the left mouse button on this variable line will open the Change 
Variable window (See p. 3-85.). One of the options under Value Format is ‘ASCII 
String’. Selecting this format and applying the change will result in the variable 
entry being updated to show the ASCII string being pointed to: 

Str_l_Par_Ref: 0x0002E248->'DHRYST0NE PROGRAM, l'ST STRING' 


Figure 3-25. Sample ASCII String Display 
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Variables of type char can also be used as the initial point for an ASCII string 
display. Consider the same string being displayed as an array of characters 
(expanded to show the first few elements): 


Str_l_Par_Ref: 0x0002E248 <ptr> 
[03: 'D' 

[13: 'hr 
[23: 'R' 

[33: 'Y' 


Figure 3-26. Sample Character Array 


Single-clicking the left mouse button on any of the character variable entries will 
open the Change Variable window (See p. 3-85.). Selecting the ‘ASCII String’ 
Value Format and applying the change will result in the character variable entry 
being updated. An ASCII string is displayed, starting from the address of the 
variable. In this case, it would probably make most sense to choose the first 
element of the array, resulting in the following format change: 


Str_l_Par_Ref: 0x0002E248 < P tr> 

C03: 'DHRYSTONE PROGRAM, l'ST STRING' 
C13: 'H' 

[23: 'R' 

_ [33: 'Y' _ 

Figure 3-27. Sample Array Element Display 

Note that in either case of using a pointer or a char as the basis for displaying the 
string, the debugger will display characters starting from the address of the 
variable until a NULL character is reached in memory or an internally defined 
maximum length is reached. 

Handling Multiple Data Elements Referenced by a Single Pointer 

Suppose we initialize a data pointer to point to a memory buffer allocated to hold 
several identical data structures.Typically, individual buffer elements can be 
manipulated by the program by using pointer arithmetic with the pointer value. It 
would be cumbersome to view and change the full range of data being pointed to 
if the pointer variable is restricted to displaying a single element. Fortunately, 
RISCWatch provides a format to aid in this task. 
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Consider the following variable, a pointer to type struct record on a Locals or 
Globals variable window. It references individual elements of a buffer containing 
multiple struct record instances, and points to the beginning of the buffer: 

Ptr_Glob: 0x00335DEF <ptr to struct record> 

Figure 3-28. Sample struct record Pointer Display 


Normally, if we were to expand this pointer, it would only expand one instance of 
the structure at the address which it is currently pointing to: 


Ptr_Glob: 0x00335DEF <ptr to struct record> 

->: <struct record> 

♦Ptr_Comp: NULL <ptr to struct record 
.Discr; +0 STRUCT_0 <enum> 

.variant; <union> 


Figure 3-29. Sample Initial struct record Pointer Expansion 


What we want to do is to be able to manipulate individual records. RISCWatch 
supports this ability by allowing a pointer variable entry to be expanded as an 
array (with a specified number of elements), with each element of the array 
subsequently being of the type which the original pointer is pointing to. 

Single-clicking the left mouse button on this variable line for the original pointer 
will open the Change Variable window. One of the options under Value Format is 
‘Show As Array’. Selecting this format option changes the entry field at the bottom 
of the window so that an array subrange (with the first element having the address 
of the pointer value) may be specified. 
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In this case we’ll specify the first three elements [0,2]: 
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Figure 3-30. Changing Pointer Variables 


Applying the changes will result in the variable entry being updated to show an 
array of three data structures, each representing one of the individual data 
elements in the buffer. 


Ptr_Glob: 0x00335DEF <ptr to struct record> 
CO]: <struct record> 

Cl]: <struct record> 

C2]: <struct record> 


Figure 3-31. Sample Pointer Variable Shown as an Array 
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Now each individual array element can be manipulated according to the treatment 
for that type. 

Ptr_Glob: 0x00335DEF <ptr to struct record> 

CO]: <struct record> 0OO335DEF 

.Ptr_Comp: NULL <ptr to struct record> 

.Discr: +0 STRUCT_0 <enum> 0OO335DF3 
.variant: <union> 0OO335DF7 

.var_l: <struct> 0OO335DF7 
.var_2: <struct> 0OO335DF7 
.var_3: <struct> 0OO335DF7 
Cl]: <struct record> ©00335E1F <48 bytes) 

.Ptr_Comp: 0x00335DEF <ptr> 0OO335E1F 
.Discr: +1 STRUCT.l <enum> 0OO335E23 <4 bytes) 
.variant: <union> 0OO335E27 (40 bytes) 

C2]: <struct record> 

.Ptr_Comp: 0x00335ElF <ptr to struct record> 
.Discr: +2 STRUCT_2 <enum> 

.variant: <union> 


Figure 3-32. Sample Expanded Pointer Variable Shown as an Array 


At any time, the original pointer can be returned to its normal pointer designation 
by single-clicking the left mouse button on the pointer variable. This action will 
open the Change Variable window. Selecting the ‘Show as Ptr’ Value Format will 
restore the pointer back to its original display. 

Changing Multiple Instances of a Variable Within an Array 

If a local or global variable is part of an array element, RISCWatch provides the 
ability to simultaneously change the format, display, or value of each instance of 
the variable within multiple elements of the array. This is accomplished by 
selecting a check box on the Change Variable window titled ‘Apply to each var. 
instance at this level’ when changes are applied. This check box is used to apply 
changes to multiple elements and will only appear on the Change Variable 
window if the selected variable is somewhere part of an array element (and more 
than one element exists for the array from the perspective of the debugger). 

If the check box is selected on a window which contains a Variable Detail 
groupbox, it will be disabled as long as the check box is selected (and any detail 
selections will be ignored if the check box is selected when changes are applied). 

If display information changes are applied, they will only apply to portions of the 
variable which have previously been ‘revealed’ or expanded, whether they are 
currently visible or not. If a value change is applied, it will only apply to the 
associated variables which are currently visible on the variable window. Also, 
when applying a change to multiple instances, a pop-up dialog will appear to 
verify the action. This underscores the fact that care should be taken when this 
option is used. 
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Consider the following variable which is an array of chars, with each element 
value currently displayed as hexadecimal: 


Str_l_Loc: <arrayC31] of char> 


to:: 

0x49 

ci]: 

0x42 

[2]: 

0x4D 

C3] : 

0x20 

C 4]: 

0x52 

C5]: 

0x49 

cs] : 

0x53 

C7]: 

0x43 

C8]: 

0x57 

[y]: 

0x61 

CIO] 

: 0x74 

cil] 

: 0x63 

C12] 

: 0x68 


Figure 3-33. Sample char Array Display 

As a simple example of applying a change to multiple elements at once, we’ll first 
select an element of the array (it doesn’t have to be the first). This will bring up the 
Change Variable window shown in Figure 3-34. Notice the check box above the 
buttons at the bottom of the window. It appears because the variable we selected 
was part of an array element. We’ll update the display so that the address of each 
element will be shown, and the value be formatted as ASCII instead of hex. We do 
this by selecting the appropriate Display Info, and Value Format options just as we 
would for any variable, along with selecting the checkbox to indicate we wish to 
apply these changes to each element. 
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—- 

Change Variable 

g 

pi 

St 



-ocal Base Variable Name? 
r_l_Loc[3] 



Read info* 

Value Format 

9 Show Address 

Of- 1- « Mrray 

□ Show Size 

Off- « Ph* 

□ Show Type 

C ASCII 

□ Use Block Read 

JASCII string 

□ Use Defaults 

: w ) Binary 


0 C as T 


Hexadecimal 


0Octal 

OH’S'? detail 

QSigned 

0 D”'"' deiai 1 

O Unsigned 

( j 

Q Default 


Change value: 

I 

9 Apply to each var, instance at this level 


OK 


Cancel 

Help 


Figure 3-34. Changing Multiple Elements of a Variable Array 
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Applying these changes results in each element being updated accordingly on the 
variable screen: 


Str_l_Loc; 


<arrayC31] of 
CO]: 'I'(0x49) 
Cl]: 'B'(0x42> 
C2]: 'M'(0x4D) 
C3]: ' '(0x20) 
C4]: 'R'(0x52) 
C5]: 'I'(0x49) 
C6]: 'S'(0x53) 
C7]: 'C'(0x43) 
C8]: 'W'(0x57) 
C9]: 'a'(0x61) 
CIO]: 't'(0x74) 
cil]: 'c'(0x63) 
C12]: 'h'(0x68) 


char> 

0OOO2E248 

0OOO2E249 

0OOO2E24A 

0OOO2E24B 

0OOO2E24C 

0OOO2E24D 

0OOO2E24E 

0OOO2E24F 

0OOO2E25O 

0OOO2E251 

0OOO2E252 

0OOO2E253 

0OOO2E254 


Figure 3-35. Updated Display of Variable Array 

Note that in the example above, we could also have initialized each element of the 
array by entering a value in the Change Value field. With a value change being 
applied to multiple instances, a pop-up dialog would first appear to verify the 
change request. Applying the value change would result in the value of each 
element of the array being changed. 

The robustness of this capability can be fully realized by understanding that it 
applies to all data types at any level of detail expansion within an array element. 
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Consider the following pointer formatted to show as array, with the first two 
elements expanded to multiple levels of detail: 


Rec_Ptr: 0x003FF6F0 <ptr> 

CO]; <struct> 

.Ptr_Comp: HULL <ptr> 

.Discr: +0 STRUCT_0 
.variant: <union> 

.var_l: <struct> 

.Enum_Comp: +0 STRUCT_0 
.Int_Comp: +0 

.Str_Comp: <array> @003FF700 
.var_2: <struct> 

.E_Comp_2: +0 STRUCT.O 
.Str_2_Comp: <array> 0OO3FF6FC 

[03: 'SxO' 0OO3FF6FC 
C1]J 'SxO' 0OO3FF6FD 
C2]: 'SxO' 0OO3FF6FE 

.var_3: <struct> 

C1D; <struct> 

,Ptr_Comp: HULL <ptr> 

.Discr: +1 STRUCT_1 
.variant: <union> 

.var_l: <struct> 

.Enum_Comp: +1 STRUCT_1 
.Int_Comp: +1 

.Str_Comp: <array> 0OO3FF73O 
,var_2: <struct> 

.var_3: <struct> 


Figure 3-36. Sample Multi-Element, Multilevel Variable Display 


Selecting the Str_Comp array variable of the first element brings up the Change 
Variable window. The check box to apply to multiple instances appears since 
ultimately this variable is contained within an array element. This time we’ll 
change the array subrange to ‘0,2’, select to show address information, and select 
the check box to apply the change to each element.Notice that the variable 
window is updated for each instance of the variable at that level in both Ftec_Ptr 
array elements. 
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Rec_Ptr: 0x003FF6F0 <ptr> 

COD: <struct> 

.Ptr_Comp: NULL <ptr> 

.Discr: +0 STRUCT_0 
♦variant: <union> 

*var_l: <struct> 

♦Enum_Comp: +0 STRUCT_0 
.Int_Comp: +0 

.Str_Comp: <array> 0OO3FF7OO 
CO]: 'I' 0OO3FF7OO 
C12: 'B' 0OO3FF7O1 
121 : 'M' 0OO3FF7O2 

.var_2: <stract> 

♦E_Comp_2: +0 STRUCT_0 
.Str_2_Comp: <array> 0OO3FF6FC 

CO]: 'SxO' 0OO3FF6FC 
Cl]: 'SxO' 0OO3FF6FD 
C2]: 'SxO' 0OO3FF6FE 

.var_3: <struct> 

Cl]: <struct> 

.Ptr_Comp: NULL <ptr> 

♦Discr: +1 STRUCT_1 
.variant: <union> 

,var_l; <struct> 

.Enum_Comp: +1 STRUCT_1 
.Int_Comp: +1 

.Str_Comp: <array> 0OO3FF73O 
CO]: 'H' 0OO3FF73O 
Cl]: 'ft' 0OO3FF731 
C2]: 'L' 0OO3FF732 

♦var_2: <struct> 

♦var_3: <struct> 


Figure 3-37. Updated Multi-Element, Multilevel Variable Display 


This last example will further explain the processing used to determine where 
changes will be applied if the option is used to change multiple instances of a 
variable within a complex structure.Selecting the first element of the Str_Comp 
variable in the first Ftec_Ptr element brings up the Change Variable Window. We’ll 
initialize each (visible) element of the Str_Comp array in this and every other 
(visible) Rec_Ptr element by putting the value in the Change Value field and 
selecting the check box to apply to multiple instances. 
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■— Change Variable >• 


—Local Base Variable Name: 

Rec.Ptr[01.variant.var_l.Str_Comp[01 


| —Read info. — 

Value Format 

W Show Address 

J*<' 

□ Show Size 

« krr 

□ Show Type 

o ASCII 

□ Use Block Read 

OASCII string 

□ Use Defaults 

Q Binary 


O Cast 


OHexadecimal 

1-Ws ' ' j f ' : 1 

O Octal 

j {•{«:'** H#> F 1 1 

OSigned 

)!..*»«'<' ! 

OUnsigned 

[9 \.t>ik v t> t\t> {• j 

• Default 

Change value: 

' A'l 


W Apply to each war. instance at this lewel 


OK 


Cancel 


Help 





Figure 3-38. Sample Change Value Display 


Now, notice the variable’s name in the window above: 

Rec_Ptr[0].variant.var_1 .Str_Comp[0]. First, all elements of this instance of 
Str_Comp will be changed. Next, going back through the name, the changes will 
also be applied to all the elements of any other instance of the Str_Comp variable. 
We can see in this example that there is another instance of the Str_Comp 
variable, in the second Rec_Ptr element having the name 
Rec_Ptr[1], variant. var_1 .Str_Comp. 
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Applying the change results in the following update: 


Rec_Ptr: 0x003FF6F0 <ptr> 

CO]; <struct> 

.Ptr_Comp: NULL <ptr> 

.Discr; +0 STRUCT_0 
.variant: <union> 

.var_l: <struct> 

.Enum_Comp: +0 STRUCT_0 
.Int_Comp: +0 

.Str_Comp: <array> ©003FF700 
to:: 'ft' 0OO3FF7OO 
[ID: 'ft' 0OO3FF7O1 
[2D: 'ft' 0OO3FF7O2 

.var_2: <struct> 

.E_Com P _2: +0 STRUCT_0 
.Str_2_Comp: <array> 0OO3FF6FC 

COD: '\x0' 0OO3FF6FC 
[ID: '\x0' 0OO3FF6FD 
[2D: '\x0' 0OO3FF6FE 

.var_3: <struct> 

[ID: <struct> 

.Ptr_Comp: NULL <ptr> 

.Discr: +1 STRUCT.l 
.variant: <union> 

.var_l: <struct> 

.Enum_Comp: +1 STRUCT_1 
.Int_Comp: +1 

.Str_Comp: <array> 0OO3FF73O 
[OD: 'ft' 0OO3FF73O 
[ID: 'ft' 0OO3FF731 
[2D: 'ft' 0OO3FF732 

.var_2: <struct> 

,var_3: <struct> 


Figure 3-39. Sample Result of Change Value Update 


All elements of the each Str_Comp array are now initialized to the character ‘A’. 
Notice that the elements of the Str_2_Comp array are not affected, even though 
the Str_2_Comp array is an array of characters nested the same number of 
levels’ from Rec_Ptr[0]. This is because it is a different variable and the changes 
were only applied to Str_Comp variable instances. 

It should be apparent that care should be taken when applying value changes to 
multiple variable instances within complex data structures. Format and Display 
changes are not destructive, but once the values are changed they cannot be 
recovered. 
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Type Casting a Variable 

The Cast format option is available on the Change Variable window to enable 
dynamic Type Casting of a variable. This feature is particularly useful when 
debugging code that contains void pointers. 

Consider a local variable called ’voidptr’ which has been defined in ’C’ code as 
'void ‘voidptr’. A single left mouse click on this variable will bring up the Change 
Variable window. 

-J_Change Variable | * 

|—Local Pointer Variable Name:-1 

voidptr 


pRead info* 

—Value Format 

□ Show Address 

QShou as Array 

□ Show Size 

QShow as Ptr 

□ Show Type 

Qh:( i 1 

J Use Block Read 

_)ASCII string 

W Use Befaults 

0 Binary 

- 1 

Cast 


:^)Hexadecimal 

[-Variable detail — 

0 Octal 

IQ More detail 

QSigned 

QLess detail 

0 Unsigned 

Leave detail 

0 Default 


Enter type (ex, int*, file:struct.a*, etc): 
user defined*I 


OK | Cancel j Help 


Figure 3-40. Sample Variable Type Cast 

Figure 3-40 illustrates the actions needed to cast ’voidptr’ to a new type: 

• Select the Cast Value Format. Notice the ’Change Value:' field near the 
bottom of the window is now prompting for a new ‘type name’. 

• Enter a valid type name followed by any number of ’*’s to indicate pointer 
indirection. Valid type names include fundamental 'C' types such as ’int’, 
’long’, 'signed char’, ‘short, etc. In addition, any user defined type name (i.e. 
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structures defined in your 'C' code) can be used. Figure 3-40 indicates 
'voidptr' will be changed to be a pointer to structure ’_user_defined'. 

• Press the ‘enter’ key or select ’OK’. RISCWatch will search for a type name 
match using the debug information defined for the source file where the 
variable was originally defined. If no match is found, an error message is 
reported in the RISCWatch main window. 

• Preceding the type name with a source file name, followed by will direct 
RISCWatch to search for a name match in the designated file. For example, 
'filel ,c:_user_defined' will force RISCWatch to search the debug information 
defined for source file 'filel .c’. Valid file names are those names found in the 
Files window. Note that the directory path of the source file does not need to 
be specified. The file name may also be enclosed in double quotes. 

• The original type definition can be restored by entering ’#default’ as the new 
type name. 

The Cast format option is available for all variables except arrays. Since an array 
variable has no value, type casting should be performed on the individual 
elements of the array. Note that multiple elements of an array can be type caste 
simultaneously by making use of the 'Apply to each var’ check box of the Change 
Variable window. 

Source Variable Command Support 

In addition to the graphical user interface support described above, local and 
global source variables can be used with memory access commands such as 
read, write, set and expr. Source variables are distinguished from other 
RISCWatch variables by a leading colon and adhere to the following syntax 
rules: 

:['filename":][&] var_name 
Where: 

• ’:’ indicates a source variable, as opposed to other RISCWatch variables, such 
as register names or address locations. 

• filename is a valid file name, as displayed in the Files Window. This optional 
field is used to address a specific global variable whose name may conflict with 
an active local, or another static global variable. If the filename option is not 
specified, RISCWatch will search for var_name in the list of locals defined for 
the current instruction address (IAR). If not found in the current function, the list 
of global debug names will be searched. 

Note: the file’s directory path does not need to be specified when designating a 
filename. 

• var_name is a valid variable name, as seen in the Locals or Globals Window. 
Normal ’C’ language naming conventions are used to identify a specific data 
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member. For example ":ptr->member1", ":ptr[0].member1", 
":structa.structb.member2" are all valid name constructs. The variable name 
must be defined within the active function (defined by the IAR) or within the 
active list of globals. 

• ’&’ is a request for the address of a variable, similar to the 'C' language 
definition. If '&' precedes a var_name that is assigned to a register, the 
address can not be determined and an error is reported. 

• is a request for the value of a var_name that resolves to a 'C' pointer. If 
precedes a non pointer variable, or the variable is a pointer to a structure, an 
error is reported. 

Typical examples: 

read :i # reads src variable ’i’ 

write :ptr[100] 14 # write decimal 14 at the 101 st element of ptr’ 

set :"file.c":glob1 .a = 0x13 # write hex 13 to variable 'globl .a’ 

read :&test[2].a R1 # write R1 with address of ’test[2].a’ 

expr :**ptr1 # display value of ’**ptr’ 


Reading and Writing Memory 

The Hardware | Memory pulldown on the Main window provides a number of 
different ways to view memory. They allow the user to view specified memory 
contents in hex, ASCII, or disassembled instruction formats. The following page 
references are good sources of information: 

• “ASCII Memory Window” on page 3-108 

• “Custom Memory Window” on page 3-110 

• “Memory Coherency Window (JTAG Targets Only)” on page 3-105 

• “Cache Windows (JTAG Targets Only)” on page 3-113 

• “Translation Lookaside Buffer Window (Applicable Processors Only)” on 
page 4-15 

• “Load Memory Window” on page 3-63 

• “Save Memory Window” on page 3-114 

Some windows also provide the ability to alter memory contents. 

Memory can also be viewed and altered using the read and write commands 
from the command line on the Main window. 

Note: Be aware that there are situations where changing the content of an 
individual memory location may result in sections of adjacent memory being read. 
If data is written to an address, and that address corresponds to an address which 
is contained in a Memory or Asm Debug window which is currently up, a memory 
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region the size of the memory displayed in these windows will be read from the 
target. Similarly, if the address of changed memory corresponds to a portion of an 
individual memory element existing on any user-defined window, an amount of 
memory equal to the size of the memory element will be read (for example, if a 
byte-sized memory element at address 0x00000001 is written, and another 
user-defined memory region is defined with four word size elements starting at 
address 0x00000000, one word of data will be read from address 0x00000000 in 
this case). 

Memory Coherency Window (JTAG Targets Only) 

The Memory Coherency window is used to control data and instruction cache 
updating during memory reads and writes. This window is displayed by selecting 
the Memory | Coherency option of the menubar’s Hardware pulldown choice. 

U Memory Coherency ^ O 

Read memory 

' Use memory model 
v Physical memory 
Write DMEM 

Use memory model 
(s DC write-thru 
^DC bypass 
Write IHEM 

V IC update, DC bypass 
IC update, DC update 

^ IC inval, DC bypass 

V IC inval, DC update 
» See Help for usage « 

Close | Help 


Figure 3-41. Sample Memory Access Window 

If caching is disabled via the appropriate hardware registers (DCCR/ICCR for 
PowerPC 400Series, HID0 for PowerPC 6xx/7xx), reads and writes from/to 
memory will directly reflect the contents of physical memory. 

If the processor is configured to control data and instruction caching, a memory 
model is said to have been established for how the data and instructions will be 
accessed. Once a memory model has been established, reads and writes to/from 
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memory will provide data and/or instructions that are a combination of information 
from the caches and memory. 

Using the read memory options, it is possible to force reads to use your memory 
model (a combination of cache and memory information) or to read directly from 
physical memory (by bypassing the data cache). 

When a memory model is used to control data caching, the Memory Coherency 
window allows control over how the data is written to the data cache and memory. 
To allow the processor to manage data coherency between the data cache and 
memory, select the memory model option. To force memory writes to immediately 
update the data cache and memory contents, select the write-thru option. To force 
memory writes to update physical memory only, and not the data cache, select the 
bypass option. 

Similarly, an instruction cache (1C) memory model can be controlled with the 
options in the Memory Coherency window. The update options should be selected 
to force instruction memory writes to update both physical memory and the 
instruction cache. The invalidate options are used to force instruction memory 
writes to update physical memory while marking the associated addresses as 
invalid in the instruction cache. 

For instruction memory writes, the data cache (DC) options are used to indicate 
whether instruction memory writes are to update the data cache or not. Select the 
bypass option to indicate that instruction memory writes are NOT to be written to 
the data cache. Selecting the update option forces instruction memory writes to 
update the data cache as well. 

WARNING: The DC bypass option should be used with caution when data 
caching is enabled. This option is used to force the data memory writes to update 
physical memory without updating the data in the data cache. This mechanism 
essentially overrides the memory model that would be set up using the registers 
which control caching. Data written to physical memory using this option could be 
overwritten by “dirty” data in the cache that had not yet been written out to 
memory. 
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Following is a description of the Memory Coherency window options and exactly 
how they function: 


1. Write DMEM 

Coherency 

D-Cache 

1-Cache 

Physical 

Memory 

Use memory model 

Yes 

Note 1 

No 

Note 2 

DC write-thru 

Yes 

Note 1 

No 

Yes 

DC bypass 

No 

No 

No 

Yes 

2. Write IMEM 

Coherency 

D-Cache 

1-Cache 

Physical 

Memory 

1C update DC bypass 

Note 3 

No 

Note 4 

Yes 

1C update DC update 

Yes 

Note 1 

Note 4 

Yes 

1C inval DC bypass 

Note 3 

No 

No (Note 5) 

Yes 

1C inval DC update 

Yes 

Note 1 

No (Note 5) 

Yes 


Notes: 

1. D-Cache updated if enabled (via DCCR for PowerPC 400Series, HIDO for 
PowerPC 6xx/7xx) 

2. Physical memory written if D-Cache disabled (via DCCR for PowerPC 
400Series, HIDO for PowerPC 6xx/7xx) 

3. Coherent if D-Cache disabled (via DCCR for PowerPC 400Series, HIDO for 
PowerPC 6xx/7xx) 

4. 1-Cache updated if enabled (via ICCR for PowerPC 400Series, HIDO for Pow¬ 
erPC 6xx/7xx) 

5. 1-Cache line invalidated 

Note: RISCWatch will ignore the settings in the Memory Coherency Window 
during a memory download (load command) and default to an l_Cache invalidate, 
D_Cache flush model. This model achieves the best download rate while 
maintaining coherency of the system under test. 
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ASCII Memory Window 

The ASCII Memory window allows memory to be read, altered and written as 
four-byte data words or as ASCII text. This window is displayed by selecting the 
Memory | ASCII option of the menubar’s Hardware pull-down choice. What follows 
is a description of this window’s functionality. 



ASCII Memory: 1 


1 

S 


(Address Data 


ASCII 





00020DA0 


80613558 80630037 90610036 80613358 


.a5X.c.7.a.6.a3X 

F 

00020DB0 


804E0000 3082617C 62840000 69A4C46C 


. N.. 0. a 1 b... i .. 1 


00020DC0 


30847318 7C70C5AA 65300061 7CA4C46B 


0.s.Ip*.eO.a 1,.k 


00020DD0 


7CA3C569 8081006E 38600067 9021000C 


1..i...n8'.g.!.. 


00020DE0 


80810038 80610058 8063000C 9064000C 


...8.a.X.c...d.. 


00020DF0 


80810038 80610058 80630000 90640000 


...8.a.X.c...d.. 


00020E00 


80610038 48000101 80610038 80630004 


.a.8H....a.8.c.. 


00020E10 


2C830000 40860058 80810038 38600006 


-0..X...88'.. 


00020E20 


9064000C 80610058 80630008 80810038 


.d...a.X.c....*8 


00020E30 


30840008 48000199 4FFFFB82 80810038 


0.. *H.. .0.8 


00020E40 


8062007C 80630000 80630000 90640000 


*b.1*c...c...d.. 

/ 


Read | Close | 1 Help | Auto-update 


i 


Figure 3-42. Sample ASCII Memory Window 


• Scroll Bar 

Clicking on a vertical scroll arrow alters the display address by one line or opcode. 
Clicking on the area between a vertical arrow and the current scroll position alters 
the display address by one screen’s worth of data. To display a given address, use 
the address entry schemes described in the Data area and Address entry 
sections. 

The page up and page down feature may also be accessed via the keyboard Page 
Up and Page Down buttons. 

• Address area 

The address area of the ASCII Memory window is used to display data anywhere 
within the configured range of the processor. The address area is located at the 
far left under the Address: heading. To display any part of memory, simply use the 
mouse to place the cursor anywhere within one of the address values, type in the 
desired address and press the Enter key. 

• Data Area 

The data area of the ASCII Memory window is used to display data read from the 
processor as well as alter this data so that it may be written back. There are four 
data values per display line with each value displaying four bytes of data. 
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To alter any of these data values, simply use the mouse to place the cursor 
anywhere within one of the data values, type in the desired data, and press the 
Enter key to write the data value to the processor memory. Changed data will not 
be written to the processor unless the cursor is in the data value that was changed 
when the Enter key is pressed. If data is mistakenly entered into a data field that is 
not to be written to memory, simply click on the Read button to refresh the 
displayed data. 

• ASCII area 

The ASCII area of the ASCII Memory window is used to display data read from 
the processor as well as alter this data so that it may be written back. The ASCII 
area is located in a column along the right hand side of the window. Each ASCII 
line contains sixteen (16) ASCII characters that represent the data bytes in the 
data area. 

To alter any of these data values, simply use the mouse to place the cursor in any 
one of the ASCII character areas, type in the desired data and press the Enter key 
to write the ASCII data to the processor memory. Changed data will not be written 
to the processor unless the edit cursor is in the data line that was changed when 
the Enter key is pressed. 

• Read button 

The Read button is used to read the processor memory to refresh the contents of 
all currently displayed data and address fields. Use this button to force a refresh of 
displayed data or to remove the contents of a partially edited data or address field 
which has not been written back to the processor. 

RISCWatch allows multiple instances of the ASCII Memory screen to be used 
simultaneously. The instance number is included after the in the title bar. Each 
time the ASCII Memory screen is selected via the Memory pulldown or the 
“window ascii” command is issued, a new instance of the window will be created. 
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Custom Memory Window 


The Custom Memory window allows memory to be written or read in several 
different formats and word sizes. This window is displayed by selecting the 
Memory | Custom option of the menubar’s Hardware pull-down choice. What 
follows is a description of this window’s functionality. 


Custom Memory:! 


Address 0 


8 


00000000 

00000010 

00000020 

00000030 

00000040 

00000050 

00000060 

00000070 


+1164796517 

+0813187393 

+0000000106 

+0000000000 

+0000000000 

+0000000000 

+0000000000 

+0000000000 


+1684301156 

+1111638851 

-0000000001 

-0000000001 

-0000000001 

-0000000001 

-0000000001 

-0000000001 


+0542142327 

+1145307136 

+0000000000 

+0000000000 

+0000000000 

+0000000000 

+0000000000 

+0000000000 


+1701990467 

+0000000000 

-0000000001 

-0000000001 

-0000000001 

-0000000001 

-0000000001 
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Figure 3-43. Custom Memory Window 


• Address Area 

The address area of the Custom Memory window is used to display data 
anywhere within the configured range of the processor. The address area starts at 
the leftmost column under the Address heading. To display any part of memory, 
simply use the mouse to place the cursor anywhere within one of the address 
values, type in the desired address and press the Enter key. 

• Data Area 

The data area of the Custom Memory window is used to display data read from 
the processor as well as alter this data so that it may be written back. The data 
area consists of all the values displayed to the right of the address area and 
underneath the numeric headings which are used to help in determining 
on-screen addresses. 

To alter any of these data values, simply use the mouse to place the cursor 
anywhere within one of the data values. The Input Area will appear at the bottom 
of the window to allow new values to be entered. When the input area is 
displayed, the Custom Memory window will be locked until the enter key is 
pressed. 

• Scroll Bar 
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Clicking on a vertical scroll arrow alters the display address by one line’s worth of 
data. Clicking on the area between a vertical arrow and the current scroll position 
alters the display address by one screen’s worth of data. To display a given 
address, use the address entry scheme described above in the Address Area 
section. 

The page up and page down feature may also be accessed via the keyboard Page 
Up and Page Down buttons. 

• Base Selection 

The base selection button is used to select the radix that the data values will be 
displayed with in the data area. To change the currently selected base, click on the 
arrow button with the mouse and select the desired base. Once done, the data will 
be refreshed and displayed in the newly selected base. 

• Size Selection 

The size selection button is used to select the word size of the data values to be 
displayed in the data area. To change the currently selected size, click on the 
arrow button with the mouse and select the desired size. Once done, the data will 
be refreshed and displayed in the newly selected size. 

• Sign Selection 

The Sign selection button is used to select the sign used to display data values in 
the data area. To change, the currently selected size, click on the arrow button 
and select the desired sign. Once done, the data will be refreshed and displayed 
in the newly selected sign. 

The sign selection button is only enabled when the currently selected base is 
decimal. 

• Read button 

The Read button is used to read the processor memory to refresh the contents of 
all currently displayed data and address fields. Use this button to force a refresh of 
displayed data or to remove the contents of a partially edited address value. 

• Input Area 

The input area of the Custom Memory window is used to input data values that 
are to be written to processor memory. This area appears when a value has been 
selected from the data area by clicking on it with the mouse. Once done, the input 
area will appear between the Help and Auto-update buttons. The value to be 
written to memory is typed in and followed by the Enter key. To cancel this input 
operation, press the Esc key. 

Note: Once the input area is displayed, the window controls will be locked to 
prevent activation until the input operation is completed or cancelled. 
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Values typed into the input area can be specified in ASCII, binary, decimal, 
hexadecimal and octal radixes. The following rules are used in the specified order 
to determine the radix being specified: 

• If the currently selected base is ASCII, an ASCII value is assumed. 

• If the value starts with 'Ox', 'OX', ’x’ or ’X’, a hexadecimal value is 
assumed. 

• If the value starts with’d’, V or a decimal value is assumed. 

• If the value starts with ’O’, an octal value is assumed. 

• If the value starts with ’b’, a binary value is assumed. 

• If the value starts with an ASCII value is assumed. 

• If the value starts with a decimal number, a decimal value is assumed. 

• All other values are assumed to be ASCII. 

When the selected base is not ASCII, an ASCII string can be specified by 
enclosing it in quotationf) marks so that it will not be confused with data in 
another radix. When the selected base is ASCII, an ASCII string is assumed so no 
quotation marks are necessary. 

When the selected base is not ASCII, input values are written to the processor as 
a single value in the currently selected word size. In other words, if an input value 
is specified which is numerically larger than that which fits in the currently selected 
word size, the "extra" data is disregarded. The exception to this rules occurs when 
an ASCII string is specified. In this case, the entire string is written to the 
processor as a series of one byte values. 

RISCWatch allows multiple instances of the Custom Memory window to be used 
simultaneously. The instance number is included after the in the title bar. The 
Custom Memory window can be resized vertically but will ignore horizontal size 
changes. 
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Figure 3-44. Sample Data Cache Window 


Cache Windows (JTAG Targets Only) 


The Data, Instruction and L2 Cache windows are used to read and display the 
contents of the processor caches. 


The processor caches are displayed one way (or side) at a time, or all together. 
The pulldown in the lower left corner is used to change the currently displayed 
way(s). The vertical scroll bar on the right is used to page up and down the 
available cache lines for the displayed way(s). 

For the Data Cache window, the following fields are shown: 

Set Set number (congruence class) down the left hand side 

Way A, B, C, etc. next to the Set number 

Address Address tag 

V Valid bit 

L LRU (Least Recently Used) line in set 

K Lock bit (401 Core+ASIC processors only) 

D Dirty bit 

Word N 32-bit data cache word N 
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For the Instruction Cache window, the following fields are shown: 

Set Set number (congruence class) down the left hand side 

Way A, B, C, etc. next to the Set number 

Address Address tag 

V Valid bit 

L LRU (Least Recently Used) line in set 

K Lock bit (401 Core+ASIC processors only) 

Word N 32-bit instruction cache word N 

Notes: For these cache displays, the address tag is always displayed normalized 
to bit 0 (MSB). 

The Way Control at the bottom left corner of the screen allows the visible way(s) to 
be changed. 

The Read button is used to force a read of the processor cache and display the 
latest contents. 

The Close button is used to remove this window from the screen. 

The Filter check box is used to filter the cache lines so that only lines which are 
presently marked as Valid are displayed. If this option is selected, a pop-up 
window will appear informing the user that enabling this feature may result in a 
performance degradation due to the large amount of data which must be 
processed. On some processors it may be desirable to disable the Auto-update 
feature when Filter is enabled to reduce update overhead. In this case, the Read 
button may be used to force the window contents to be updated. 


Save Memory Window 

The Save Memory window provides target memory read capabilities using the file 
format options defined for the Save command. The window is displayed by 
choosing the ‘File’ pulldown on the RISCWatch Main window, then selecting Save 
| Memory. 
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Figure 3-45. Save Memory 

The Save Memory window consists of the following fields: 

• File 

This field indicates the file name to be created. The file name can be altered by 
choosing the “Select File” button at the bottom of the window or by directly 
typing in the field provided. When the Save pushbutton is pressed, RISCWatch 
will prompt the user for permission to erase the file if the file currently exists. 

• File Formats 

This group box provides a list of supported file formats. See “save," p. 5-115 for 
a description of the supported file formats. Choosing a particular file format will 
result in the enabling, or disabling, of the remaining input areas of the window. 

• Start Address 

This field is enabled for Memory and Binary format selections and indicates the 
initial target address to use when reading target memory. 

• Number of Bytes 

This field is enabled for Memory and Binary formats and indicates the number 
of memory bytes to read. 
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• Save 

This pushbutton is used to execute the selected Save command. The 
RISCWatch main window will indicate the success or failure of the operation. 

• Select File 

This pushbutton presents a standard dialog window that allows the user to 
supply a file name. The file chosen will be used to save the requested 
information. 

• Hide 

This pushbutton removes the Save Memory window from view. A subsequent 
display of the Save Memory window will present the field settings that were in 
existence when the ‘Hide’ button was pressed. 

• Help 

This pushbutton will present any available help topic for this window. 


Reading and Writing Registers 

The Hardware | Register pulldown on the Main window provides the ability to view 
and update the architected registers of the target chip. They are divided into 
classes: 

• General Purpose Registers (GPRs) 

• Special Purpose Registers (SPRs) 

• Device Control Registers (DCRs): 400Series only 

• Segment Registers (SRs): PowerPC 6xx/7xx only 

• Floating Point Registers (FPRs): processors with FPUs 

• ASIC Registers (ASICs): defined in user-created PRD files 

See “Register Windows” on page 3-117 and “Register Field Windows” on 
page 3-118 for detailed descriptions of the register windows. Register Field 
windows are used to manipulate individual fields of selected registers. These 
provide a bit breakdown of the selected register divided into logical field groupings 
applicable to the register. 

Registers can also be viewed and altered using the expr, read, set, and write 
commands from the command line on the Main window. 
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Register Windows 

Register windows are used to read, display, modify and write-back processor 
registers. Register windows are broken up into classes based on the types of 
registers they contain. Current register windows include General Purpose 
Registers (GPR), Special Purpose Registers (SPR), Device Control Registers 
(DCR: PowerPC 400Series only), Segment Registers (SR: PowerPC 6xx/7xx 
only) Floating Point Registers (FPR: processors with FPUs) and ASIC Registers 
(ASIC: defined in user-created PRD files). To bring up a particular register 
window, use the Hardwarel | Register pulldown of the Main window menubar. 
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Figure 3-46. Sample Register Window 


Note: RISCWatch will only display an ASIC selection for the Register 
pulldown if a custom PRD file is being used and the ASIC registers 
defined in the PRD file followed the prescribed naming convention for 
such registers. Refer to the REG Definitions section of “Processor 
Configuration File (PCF)“ for register naming details. 

Note: If an ARIC Register window is selected, more than one physical 
window may appear if RISCWatch determines that there are too many 
registers for a single window to hold (as dictated by the physical 
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constraints imposed by the user interface). If this is the case, the 
multiple windows created can be thought of as one logical entity. 

Therefore, pressing the Read or Close buttons on one window applies 
to all of them (with the same ASIC register prefix). If a specific subset 
of ASIC registers is desired for read or write operations, simply create 
a User-Defined window to access them. 

A register window is split into two or more columns with each column containing a 
push button and register edit field. The push button contains a register name while 
the edit field contains its value. The push button is used to bring up a register field 
window for that particular register (if it has a field definition). Use the mouse to 
press the push button and bring up its register field window. If it has no field 
definition, an error message will be displayed. 

To edit a register value, use the mouse to place the edit cursor in the appropriate 
field and enter a new hexadecimal value for the register. This new value will not be 
written to the processor unless the edit cursor is in the field and the Enter key is 
pressed. 

To refresh the contents of all register fields at any time, use the mouse button to 
click on the Read button located at the bottom of the window. 

Register Field Windows 

Register field windows are used to read, display, modify and write-back processor 
registers. To bring up a particular register field window, use the Hardware|Reg 
Fields pulldown of the Main window menubar. 


A register field window is composed of one or more registers. Each register 
definition in the window takes up one display line. This line is composed of the 
register name, a register value field and register field value fields. 
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The register value field contains the full data value for the register and should 
track to the value of the register in its Register window. This field may be edited 
and written to the processor just like its counterpart in the Register window. 

The register field value fields are a series of fields that represent the individual 
logical bit groupings for that register. Each field value contains a heading which 
matches the register bit definitions in the PowerPC User’s Manual for that specific 
processor. The heading is a two or three character mnemonic derived from the 
field’s name. 

For each register field, the appropriate bits are extracted from the register value, 
shift to bit zero to normalize them, and then displayed in their appropriate field. 
Such a display allows these field values to be compared directly with the values in 
the User’s Manual for that register, edited and written back to the processor. 

Register or register field values may be modified by using the mouse to place the 
edit cursor in the appropriate input field and then typing new hexadecimal values. 
This new data will not be written to the processor unless the Enter key is pressed. 

For register fields which are only one bit in size, the mouse may be used toggle 
the current bit value and write it back to the processor. To do so, simply use the 
mouse to double-click over the single-bit field. 

Whenever data is changed and written back to the processor, the appropriate data 
fields in the window will be updated to reflect this latest value. If the register value 
is changed and written, the field values will be updated accordingly. Likewise, if 
one or more register field values are changed and written, the register value will 
be updated. 

To refresh the entire window’s contents with the latest processor data, simply use 
the mouse to click on the Read button. This will read the latest data value for all 
the registers in the window and update the display accordingly. 

WARNING: Any data that has been changed in the window and not written back 
to the processor will be lost! 


User-Defined Windows 

User-Defined windows allow a RISCWatch user to create windows containing 
customizable register, register field, memory, disassembly, and button entries. 
Using a simple syntax, ASCII files are created to define the contents of a 
user-defined window. 

Note: Look for the file RWPPC.WDF in the install directory for an example of a 
User-Defined window file. We recommend that you make a copy of this file and 
then work off of this copy as you experiment with defining your own windows. 
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File Syntax 


The file used to describe a user-defined window is a simple ASCII file that is 
created with a text editor. The filenames for such files usually, but do not have to, 
end in .wdf (window descriptor file). 

The file is composed of simple keywords and may contain comments. The 
keywords used to define the contents of user-defined entries are BUTTON, 
BUTTONDEF, CMDLINE, DIS, FORMAT, HEADING, LABEL, MEM, REG, 
REGFLD, SEPARATOR, STATUSBAR, and TITLE. These keywords and their 
usage are explained in the sections that follow. 

The general syntax rules are as follows: 

1. The following keyword definitions must appear on a line by themselves 
BUTTONDEF, CMDLINE, FORMAT, HEADING, SEPARATOR, STATUS- 
BAR, TITLE 

2. The following keyword definitions may only appear once in the file 
CMDLINE, STATUSBAR, TITLE 

3. Except for those listed above, multiple keywords may be listed on a single 
line. 

4. Comments in this file are defined by starting a line with a '#’. Comments may 
also appear at the end of a line. 

5. Blank lines are ignored except where they are used to mark the end of a 
BUTTONDEF definition. 

Keyword Definition/Syntax 

• BUTTON - User Defined Button Placement Entries 

Buttons corresponding to user defined functions can be placed in the user defined 
window. The BUTTON keyword is followed by a button identifier that was 
previously defined using the BUTTONDEF keyword 

• BUTTONDEF - User Defined Button Function Definition 

Users can define their own buttons and corresponding function for inclusion on 
the window. The BUTTONDEF keyword is followed by a button id (to be used to 
place the button using the BUTTON keyword), followed by the button name (to 
appear on the screen) enclosed in quotation marks. On subsequent consecutive 
lines (no blank lines), valid RISCWatch commands can be entered, one per line. A 
blank line ends the button definition. Whenever the button is pressed on the user 
defined window, those actions listed in the definition will be executed. 

• CMDLINE - Command Line Entry 

A user defined window may also contain a command line. This command line 
allows RISCWatch commands to be entered from the user defined window in the 
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same manner they are normally entered from the main window. Only one entry is 
allowed per window definition, and it can be the only command on that line. 
Regardless of where the definition keyword is located, the command line will 
appear at the bottom (or next to the bottom if a status bar is defined) of the user 
defined window. If the window locks its controls, the only commands which are 
valid to be entered are STOP and QUIT. 

• DIS - Disassembly Entries 

Disassembly entries are used to place disassembly text in the user-defined 
window. The DIS keyword is followed by the address of memory to be 
disassembled, which is followed by the number of words to be displayed. 

• FORMAT- Format Entries 

Format entries are used to define the width of user interface controls so that 
effected controls conform to a common size which ensures that these controls are 
laid out in “pretty” columns. 

By default RISCWatch will select a default FORMAT size which doesn’t always 
result in nice, orderly columns. Using FORMAT allows the user to override these 
default rules and select values which results in user interface components which 
are laid out in an orderly fashion and therefore are easier to interact with. 

The FORMAT keyword is followed by either MEM, REG or REGFLD, the equal (=) 
sign, and a number which represents the request size of the effected control. For 
REG and REGFLD entries, this number sets the width of the push button (in 
characters) containing the register name. For MEM entries, it sets the number of 
columns in the displayed memory pane. Once set, a FORMAT selection will 
remain in effect until overridden by another. Setting the number to 0 will cancel the 
user selection and return to default sizing of controls. 

• HEADING - Window/Section Headings 

The user-defined window is given a title by using the HEADING keyword followed 
by the desired window title. The HEADING keyword can also be used to add titles 
to different sections within the window as well. 

• LABEL - Label Item Entries 

Labels can be placed throughout the window. The LABEL keyword is followed by 
the desired label text enclosed in quotation marks. 
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• MEM - Memory Entries 

Memory entries are used to place memory data in the user-defined window. 

A memory entry consists of the memory keyword MEM, followed by the address 
of memory to be displayed, followed by the number of bytes in each word, followed 
by the number of words to display. 

The leftmost field of each memory line is the address field. Placing the cursor in 
an address field and pressing Enter will result in the amount of memory displayed 
in the line being read starting at the specified address. The address can also be 
changed by typing over the current address and pressing Enter. This will also 
result in a memory read of an entire line’s worth of data. 

The contents of an individual memory element can be written by typing in the new 
value and pressing Enter. This will only write an amount of memory equal to the 
size of the individual memory element (i.e., word, half-word, or byte). 

• REG - Register Entries 

Register entries are used to place registers in the user defined window. Each 
REG keyword is followed by any valid processor register name. Multiple REG 
name pairs are allowed on a single line. 

• REGFLD - Register Field Entries 

Register field entries are used to place register field values in the user defined 
window. The REGFLD keyword is followed by the name of a valid processor 
register that has a valid field defined. 

• SEPARATOR - Section Separator Entries 

The user defined window can be separated into various sections to improve 
readability and clarity. The SEPARATOR keyword provides a graphical horizontal 
separator between window sections. This keyword must be the only keyword on 
the line. 

• STATUSBAR - Status Bar Entry 

The user defined window may also include a status bar if desired. Specifying the 
STATUSBAR keyword will include a status bar with similar content to that of the 
main window status bar. This keyword must be the only keyword on the line. 
Regardless of where the keyword appears within the file, the status bar will be 
located on the bottom of the user defined screen. 

• STOP - Processor Stop Button 

In order to stop the processor, a special button can be placed in the user defined 
window. Even though the window may lock its controls while the processor is 
running, this button will remain available for use ensuring that the processor can 
be stopped. 
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TITLE - Window Title 


A title definition allows you to provide a custom name for a user-defined window. 
By default, RISCWatch assigns the name “User-Defined” to each user-defined 
window which is loaded. While this may be fine for a single user-defined window, if 
you decide to load several at one time, it is easier to manage them if they are each 
given unique titles. 

To define a customer name for a window, simply follow the TITLE keyword by the 
name of the window between quotation marks (“). 

Creating the Window 

A user-defined window is created by using the User-Def Win entry of the 
User-Defined menu of the Window pull-down. This will display a file selection 
dialog allowing the window descriptor file to be chosen. Once a file has been 
selected, it will be read by RISCWatch. If no errors were detected, the 
user-defined window will be created for use. Alternatively, the window command 
can be used to bring up the window. The syntax is “WINDOW UDW filename”, 
where filename indicates the fully qualified name of the user defined window 
definition file. 


Example 

The following example illustrates the use of the user-defined window file syntax: 
# Provide a custom window title 
TITLE “Custom #1“ 


# Miscellaneous heading 

LABEL “The window they forgot to design for me!" 
SEPARATOR 

# Button Definition Section 
BUTTONDEF Buttonl “Read R1-R3” 
read R1 

read R2 
read R3 

BUTTONDEF Button2 “Load & Run” 
load file demo.elf 
bp set in main 
run 

# 
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# Window Layout section 

HEADING “The Window they forgot to design for me 
SEPARATOR 

HEADING “ASIC Registers” 

REG ASIC01 REG ASIC02 
SEPARATOR 

LABEL “Stack Regs : “ REG RO REG R1 

REG R14 LABEL “<- Key Reg for my application” 

SEPARATOR 

REGFLD MSR 

SEPARATOR 

MEM OxCOOO 4 4 

SEPARATOR 

DIS OxOOOOAOOO8 

SEPARATOR 

BUTTON Buttonl BUTTON Button2 

SEPARATOR 

CMDLINE 

STATUSBAR 


3-124 


RISCWatch Debugger User's Guide 



When coded as above, the window file will produce the window, Figure 3-48. 



Command Files 

RISCWatch command files are ASCII text files which contain commands that are 
understood by RISCWatch. Various commands allow for access to almost all of 
RISCWatch's processor functionality. These command files are designed to be 
human-readable and therefore can contain comment and blank lines. 

The commands contained in a command file are the same as those commands 
that can be typed into the command line of RISCWatch's Main window. See the 
following sections for a list of available commands and their usage. 
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Using Shell Scripts to Execute Command Files 

By using a shell script, several command files could be generated, one for each 
piece of logic or function to be tested, and then the entire suite could be called 
from within a single script file and allowed to run overnight. At some later time 
when the test suite was completed, the output files from the test suite would be 
checked to verify the status of each test file run. 

Startup Command File 

RISCWatch allows a pre-defined command file to be executed every time the 
program is brought up in graphical user interface mode. 

This command file, identified with the STARTUP_FILE environment variable in 
rwppc.env, may be used to perform a series of commands which would normally 
be entered on the command line whenever RISCWatch is started. This enables a 
user to set up the debugging environment and/or specific processor facilities. 

The startup command file is searched for using the following rules: 

• If the file name is qualified (directory path indicated), the file search is 
performed using the specified directory only. 

• If the name is not qualified, the file search is performed using the directory 
paths designated with the RISCWatch SEARCH_PATH environment 
variable. If not found, the current directory is searched. 

This search scheme allows individuals to create their own startup command file 
by placing it in their own directories. This also allows one startup command file to 
be placed in a common directory so that everyone will execute it whenever 
RISCWatch is started. 

Note: Commands in the startup command file are executed after the environment 
file is read. Therefore, search paths set with the SEARCH_PATH environment 
variable will be overridden by srchpath commands in the startup command file. 

Special Command File Commands 

The following commands can only be used from within a command file: 

delay Delays command file execution for the specified number of 

seconds. 

end Forces the immediate termination of the command file. 

parms Specifies a parameter variable list for the command file. See 
“Command File Parameters” on page 3-130 for details. 

print/fprint Takes the contents of the command after the print/fprint keyword 
and prints them in the host window/print file. See the fprint 
command for details and available formatting options. 
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Blank Lines and Comments in Command Files 

To make the command files more readable, blank lines can be placed anywhere in 
a command file. Comments can also be added to help document the command 
file. 

The # character indicates the beginning of a comment on a line. The # character 
can be placed anywhere on a line. Everything after the # character on a line is 
taken as a comment. Comments do not carry over onto the lines that follow them. 
An example command file that uses comments is shown below: 

# This is a sample command file 

# In this command file are examples of comments that start 

# in column 1 and comments that start after a command on a line, 
stop # This command stops the processor 

run # This command starts the processor running 

Command File Programming 

The following programming logic and flow commands are available for use in 
RISCWatch command files. These logic and flow commands are not understood 
by RISCWatch's command line interface and are therefore only valid in command 
files. 


• if-then 

if (expression) 
block 
endif 

• if-then-else 

if (expression) 
block 
else 
block 
endif 


if (expression) 
block 

elseif (expression) 
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block 

endif 

if (expression) 
block 

elseif (expression) 
block 
else 
block 
endif 
• while 

while (expression) 
block 
endwhile 
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do-while 

do 


block 

dowhile (expression) 

• goto 

LABEL label_name 
block 

GOTO label_name 
Where: 

block Represents one or more RISCWatch commands. 

expression Composed of either a mathematical or logical expression. See 
the set command for a detailed description of RISCWatch 
expression syntax. Most expressions take the form 

(argument operator argument) 

Arguments can be references to registers, register fields, 
memory values, immediate values or created/assigned 
variables. The operator(s) used in an expression are dependent 
upon the arguments used. Examples of operators in a 
mathematical expression are + and - while examples of 
operators in a logical expression are == and >. Arguments can 
also be predefined special expressions as described below. 

Regardless of whether a mathematical or logical expression is 
specified, RISCWatch will evaluate the expression accordingly. A 
logical expression will always evaluate to either a 1 (TRUE) or 0 
(FALSE). A mathematical expression will evaluate to a resultant 
mathematical value and this value will indicate FALSE if equal to 
zero and TRUE all other times. 

Iabel_name The label can consist of any characters but MUST begin with a 
letter. 

Command File Special Expressions 

Several special expressions can be used by themselves in an if, while, or do 
expression. For each expression, RISCWatch determines its state and returns a 
Boolean value used to evaluate the expression. These special expressions 
include: 

proc_running Returns 1 if the processor (JTAG) or process (non-JTAG) is in 
the run state, else returns 0. This expression is useful in 
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detecting a processor stop request failure which may occur on a 
run timeout command. For all other situations, this expression 
will return a value of 0 (since command file expressions are 
evaluated only when the processor is stopped). 

proc_stopped Returns 1 if the processor (JTAG) or process (non-JTAG) is in 
the stopped state, else returns 0. This expression is useful in 
detecting a processor stop request failure which may occur on a 
run timeout command. For all other situations, this expression 
will return a value of 1 (since command file expressions are 
evaluated only when the processor is stopped) 

run_timeout Returns 1 if the processor/process was stopped due to a run 

timeout since the run command was given. This value is cleared 
on program start and is reset every time a RUN command is 
issued. After a RUN is completed, this value will remain valid 
until the next RUN is issued. 

stop_timeout Returns 1 if the processor/process was stopped due to a stop 
timeout since the stop command was given. This value is 
cleared on program start and is reset every time a STOP 
command is issued. After a STOP is completed, this value will 
remain valid until the next STOP is issued. 

To use these special expressions, simply put the desired expression between the 
() characters of an if, while or do construct. 

Command File Parameters 

When starting a command file to be run by RISCWatch, it is possible to pass 
values into the command file using RISCWatch command file parameters. 

To do so, two things must be done: 

1. A parameter list must be supplied with the command filename 

2. A parameter definition must be specified in the command file 

A parameter list is a set of one or more values enclosed by the '{' and '}' 
characters. If more than one value is specified, they must be separated by 
commas (,). 

A parameter definition takes the form of the keyword parms followed by a list of 
the parameters that will take on the values specified in the parameter list. This list 
is composed of one or more variable names enclosed by the '{' and '}' characters. 

To enhance readability and maintainability of a command file, it is suggested that 
the parms command be the first command of a command file, although 
RISCWatch does not explicitly require this. 
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When the parms command is read by RISCWatch, it immediately creates the 
variables and assigns each int or float variable a value of 0 or string variable a 
null, just as though a create command was executed with no initial value. This 
allows these variables to be used as normally created variables even if no 
parameter list is specified. 

The following command could be used in a command file to create three 
command file variables to be used as parameters: 

parms {varl, var2, var3} 

Notice the space between the parms command and the '{' character. This space 
must be there for RISCWatch to identify the command. 

To pass outside values into the command file and have them assigned to these 
variables simply call the command file like this: 

rwppc file.cmd{10, 20, 30} 

Notice that there is no space between the command filename and the '{' 
character. 

For this example, varl would be assigned a value of 10, var2 a value of 20, and 
var3 a value of 30. The values passed in the parameter list are assigned in 
sequence to the variable names in the parameter definition. 

It is possible for the caller to specify fewer parameters in the list than are in the 
parameter definition. Using the previous example, if the command file was 
executed with the following call: 

rwppc file.cmd{10, 20} 

the variable varl would have a value of 10, var2 a 20 and var3 a 0. Since all 
parameter variables are assigned a value of zero (0) when they are created, if no 
value for them is specified in the parameter list, they remain zero (0). 

Similarly, if no parameter list was specified, all the variables would have a value of 
zero (0). A parameter list can also be specified when executing a command file 
from within RISCWatch using the exec command. 

Command File Pseudo-Variables 

There are a few special variables that are available for use but they can not be 
used like normal variables. Hence they are called pseudo-variables. 
Pseudo-variables are used to determine the values of certain system resources. 
They can not be read or written in the normal sense. However, they can be used in 
set expressions and/or referenced inside a print or fprint command. 
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The RISCWatch pseudo-variables include: 


$DATE 

$ERRORS 

$FILESIZE 

$1P_FILE 

$IP_FUNC 


Contains the current calendar date. The format of this 
pseudo-variable is weekday month day year. This may be 
used in a print/fprint command only. 

Contains the number of program errors generated since 
RISCWatch was started. This may be used in a set 
expression or a print/fprint command. The program error 
count can be reset at any time by issuing “set $ERRORS 
= 0 ”. 

Contains the number of bytes loaded from the last 
successful load command. This may be used in a set 
expression or a print/fprint command. 

Indicates the source file name associated with the current 
IAR setting. The file name is qualified and will match the 
names listed in the Files window. If the IAR is not 
associated with a specific file name, this variable will be 
set to 

Indicates the function name associated with the current 
IAR setting. The function name will match the names 
listed in the Functions window. If the IAR is not 
associated with a specific function, this variable will be 
set to 


$IP_FUNC_END Indicates the first address beyond the end of the function 
associated with the current IAR. If the IAR is not 
associated with a specific function, this variable will be 
set to zero. 

$IP_FUNC_START Indicates the first address of the function associated with 
the current IAR. If the IAR is not associated with a 
specific function, this variable will be set to zero. 

$1P LINE Indicates the file source line number associated with the 

current IAR. If the IAR is not associated with a specific 
source line, this variable will be set to zero. 

$IP_PROG Indicates the program name associated with the current 

IAR setting. The program name is qualified and will 
match the names listed in the Programs window. If the 
IAR is not associated with a specific program name, this 
variable will be set to 

$STOP_ON_ERROR This variable is always set to zero when command file 

processing is started. Setting this variable to one will halt 
command file execution if an error message is generated. 
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$TIME 


Contains the current clock time. The format of this 
pseudo-variable is hour:minute:second. This may be 
used in a print/fprint command only. 

$TIMER Contains the current timer value. See the timer command 

for details. This may be used in a set expression or a 

print/fprint command. 

Command File Programming Example 

The following is an example that uses command file programming logic to set a 
register variable based on the value of the IAR. In the example, a while loop is 
executed a maximum of 20 (count) times. The value at memory address location 
0xFFFF8000 is added to the contents of GPRO and compared to the IAR. If the 
IAR is greater than this value, register variable SI (and hence R2) is set to the 
loop count value; otherwise the value of GPRO is increased by 0x1000 for the next 
loop iteration. 

assign SI = R2 
create count = 20 

while (count != 0) 

if (IAR > R0 + (0xFFFF8000)) 

set SI = count 
set count = 0 
elseif 

set R0 = R0 + 0x1000 
set count = count -1 
endif 
endwhile 

Running a Command File 

Command files can be run from within RISCWatch using the exec command or 
they can be run by passing their filename to RISCWatch on the command line 
when RISCWatch is started. 

If a command file parameter is passed to RISCWatch at program startup, 
RISCWatch is put in command file batch mode. In this mode, each of the 
commands in the file are executed without enabling the graphical user interface. 
Once the last command in a command file executes, RISCWatch terminates itself 
and returns control to its parent process. This allows RISCWatch to be run from 
either a host command prompt or called from within a host shell script. 

To run a command file from within RISCWatch, type in the following on the 
command line of the user interface: 
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exec command_file step or window cfss command_file 

To run a command file at program startup in command file batch mode (no 
graphical user interface provided), type in the following at the shell prompt: 

rwppc command_file 

To run a command file at program startup in normal mode (with the graphical user 
interface enabled), add the following line to the rwppc.env file: 

STARTUP_FILE = command Jile 

Where: 

command_fileThe name of the command file to be executed. For example: 
test.cmd 

step Runs the command file in step mode. This option is only valid 

when executing a command file from the user interface. See 
“Command File Window” on page 3-135 for more information on 
running a command file using step mode. 
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Command File Window 


The Command File window allows a command file to be run in an interactive 
session for development and debugging. It also allows the command file to be 
edited and saved. The following section describes the functionality of this window. 



Command File 11 

=n 

Line 

File : /sld/rw/regress/ruirgr^cnd 

19 » 

PARMS Ctest_num, keepgoing} ! 

'i 

■ 

20 

FCTRL NEW rwrgr.prn # open file to print test resu | 

1 

21 



22 

if (keepgoing) 


23 

CREATE ST0P0NERR =0 # do not stop on any errors 


24 

else 


25 

CREATE ST0P0NERR =1 # stop if test group failed in any w 


26 

# regression or program error 


27 

endif 


28 



29 

EXEC testinit.cmd 


30 



31 

SET SINGLE_TEST = 0 


32 

if (test_num != 0) 


33 

SET SINGLE_TEST = test_num 


34 

endif 

j 
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Continue 
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Skip 


Save 
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Close 


Help 


Figure 3-49. Sample Command File Window 


• Filename 

At the top of the window, the current command file being run is displayed. If the 
save option is used to save an edited command file and a different name is 
chosen, this filename will be changed to reflect the new command filename. 
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Line subwindow 


The Line subwindow is used to display the line numbers of the command file, 
active stop points, and the next line of the command file that will be executed 
(designated by the command cursor symbol As commands are executed, 
the cursor will move to the next executable line, skipping blank and comment 
lines. 

A single left mouse click in this subwindow will toggle a stop point (designated by 
the characters ‘SP’). A stop point is used to halt command file execution when the 
selected line is about to be executed. Stop points are used in conjunction with the 
Continue button to quickly run to a specific location in a command file. 

To execute the Run To and Go To actions, place the cursor on a specific line 
number and hold down the right mouse button. A selection list will appear, 
allowing the user to choose the desired function. The GoTo selection will cause 
the command cursor symbol to be changed to the target line, while the RunTo 
selection will set a stop point at the target line and run the command file to that 
location. 

• Text subwindow 

The Text subwindow is used to display the contents of the command file. When 
the Command File window is initially invoked, the contents of the command file 
will be read and placed in this window. 

To change the contents of the window, simply use the mouse to place the edit 
cursor in the desired location, and then enter new text or delete existing text. To 
save your changes, use the Save button (see description below). 

• Step button 

The Step button is used to execute the command which appears next to the 
command cursor. 

• Continue button 

The Continue button is used to run the command file until a stop point is reached, 
the Halt button is selected, or the command file terminates. 

• Halt button 

The Halt button is used to halt command file execution. 

• Reset button 

The Reset button is used to reset the execution pointer to the first command in the 
initial command file. The Text subwindow will be scrolled to the top and the 
command cursor will be placed next to the first executable command of the file. 
The $STOP_ON_ERROR pseudo variable is reset to zero. For details of pseudo 
variable usage, see “Command File Pseudo-Variables” on page 3-131. 
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Clear SPs button 


The Clear SPs button is used to remove all stop points. 

• Skip button 

The Skip button is used to skip execution of the command appearing next to the 
command cursor. The command cursor will be placed beside the next executable 
command in the file. 

• Save button 

The Save button is used to save the contents of the Text subwindow. A file 
selection dialog box will allow any changes made to be saved in either the existing 
file or a new command file. 

• Return Step button 

The Return Step button is used to run through nested command file executions. 
When pressed, the current command file is run to completion and execution will 
stop at the line containing the nested exec command. 

• Close button 

The Close button is used to remove the Command File. Be advised that any 
changes made to the Text window that have not been saved will be lost! 

• Help button 

The Help button will display help text for this window. 

• Additional Features 

The Page Up/Down keys enable page scrolling of the command file. The up/down 
arrow keys are used to move the displayed text by a single line. 

For details on how to perform character string search operations, or how to quickly 
scroll to a specific source line number, see “Input Line Usage” on page 3-48. 


Processor Resources 

For PowerPC processors, RISCWatch can reset a target processor through its 
JTAG test port. Exact debug functions are specific to individual PowerPC 
processors. 
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Processor Reset Window (JTAG Targets Only) 

This window is used to access the reset functions of the processor. The three 
different kinds of resets available are Core, Chip (Core + ASIC) and System. 
Each reset performs a slightly different function. 

For PowerPC 400Series processors, please refer to the appropriate processor 
User’s Manual for a description of each reset. 

For PowerPC 6xx/7xx processors the Core and Chip resets are equivalent. They 
will reset the processor and soft stop at address OxFFFOOIOO. Also, the System 
reset will reset the processor and run from address OxFFFOOIOO. 


Proc Reset 

r— Reset- 

A Core 
^ Chip 
V System 


Reset 


Close 


Help 






Figure 3-50. Sample Processor Reset Window 


This window consists of three buttons which are used to select the type of reset 
that is desired. Use the mouse to select the appropriate reset then click on the 
Reset button located near the bottom of the window. To monitor the status of the 
reset, watch the contents of the message window. This status will indicate, among 
other things, whether the processor is running or stopped after the reset was 
performed. 


General Resources 
Window Layout 

The window layout feature of RISCWatch is used to save the position and size of 
each visible window so that the exact screen layout can be loaded thereafter. If 
the LAYOUT variable in the environment resources file, rwppc.env, is set to 
LOADSAVE, RISCWatch automatically saves a window layout when the program 
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is exited. This allows RISCWatch to load the same window layout the next time it 
is started. 

To save the current window layout, access the Window|Layout|Save option of the 
Main window menubar. This will display a file selection dialog that can be used to 
specify an existing layout file or to create a new layout file of your choosing. 
Select an existing filename or type in a new filename and click on OK. This will 
save the window layout to the specified file. By allowing users to select their own 
files, RISCWatch allows multiple screen layouts to be saved to facilitate the needs 
of multiple users or resource dependent debugging needs. 

To load a window layout, access the Window|Layout|Load option of the Main 
window menubar. Select the layout filename using the file selection dialog. The 
specified layout file will be accessed to configure the window layout just as it was 
saved. 

Output Window 

— 
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ERROR : command not found 
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WARNING : current Source file <?) has no 


H I T 
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Clear Hide Help 

I 1 ■ .■ 

Figure 3-51. Sample Output Window 

The Output window is used to display user-selectable messages generated when 
RISCWatch commands are executed. It is particularly useful when used to 
monitor the progression of long running command files, but can also be used 
whenever desired. The following section describes the functionality of this window. 
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• Message Window 

The message window is used to display the type of messages that have been 
selected. Attached to this window are vertical and horizontal scroll bars used to 
view text that lies beyond the boundaries of the visible window. 

• Message Check Boxes 

The message check boxes are used to select the types of messages that will be 
displayed. Use the check boxes to configure the types of messages you would like 
to display. 

• MPS Tag Check Box 

The MPS tag check box is used, when in MPS mode, to tag each message with 
the MPS id from which it was generated. To turn off this tagging, simply unselect 
this check box. 

This check box is only available for use when in MPS mode. 

• Clear Button 

The Clear button is used to clear the contents of the message window. 

• Hide Button 

The Hide button is used to remove the Output Window from the interface. 

• Help Button 

The Help button will display help text for this window. 
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Window List 


The window list is used to display any active window. An active window is a 
window that has been created by RISCWatch or by a user and may or may not be 
visible on the screen. This feature is particularly useful when a large number of 
windows are on the screen which may hide one or more windows from view. 

By accessing the Window|List option of the Main window menubar, a window will 
be displayed that lists all of the active windows. Use the mouse to select the 
desired window and this window will be made visible and placed on top of all other 
RISCWatch windows. 


Log Files 


Every time that RISCWatch is started, a log file is opened. Log files are used by 
RISCWatch to log all commands entered by the user, actions accessed via the 
graphical user interface, the results of actions, and all status and error messages. 
Each entry put in a log file is time stamped so that the exact times of actions can 
be recalled if they will be needed at some later date. 

Log files also allow for the sequence of actions to be recorded so they may either 
be repeated, performed again in the exact same sequence, or for a system 
operator to figure who's been doing what with RISCWatch and the processor it is 
connected to. 

RISCWatch creates a new log file for each day that it is started. When 
RISCWatch is started, it notes the month and day and looks to see if a log file 
already exists for this date. If a file does not exist, RISCWatch opens a new file for 
logging. If a file does exist for this date, RISCWatch simply opens the existing file 
and appends all new log entries to the end of the file. 

RISCWatch log files are given names to reflect the month and day they contain 
log entries for. For example, if you were to run RISCWatch on August 19, after 
leaving RISCWatch, there would be a file in the current directory called 
RW0819.LOG. This naming convention allows for several months, or even years, 
of development time, effort and methodology to be tracked and/or used to 
generate status and activity logs. 

When RISCWatch is started, logging of all entries is automatically enabled. By 
using the Logging option of the Utilities pull-down menu in the main program 
window, or the logging command, it is possible to disable logging if need be. It is 
also possible for any user to place their own comments in the log file by using the 
Utilities|Logging|Comment pull-down or the log command. 

By using a resource defined in the RISCWatch environment file (rwppc.env), it is 
possible to specify the directory where all log files are kept by RISCWatch. The 
name of the resource is LOG_FILE_DIR. The following is an example of how to 
use this resource in the rwppc.env file: 
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LOG_FILE_DIR = /u/rwppc/log_files 

RISCWatch will detect this resource and maintain all log files in the specified 
directory. 

Logging Control 

By default, RISCWatch saves all commands and messages to the current log file. 
At certain times, it may be deemed necessary to disable this functionality. To 
control the state of logging, the logging command or the Logging State window is 
used. 

To determine the current logging state, enter the logging command on the 
command line in the Main window and note the message displayed in the 
message window. To turn off logging, type ‘logging off' on the command line. To 
turn logging back on, type ‘logging on’. 

The same actions can be accomplished using the user interface. Select the 
Utilities|Logging|State option of the Main window menubar. This will display a 
small popup window indicating the current logging state. To switch logging states, 
select the Yes button. To leave the logging state as is, select the No button. 

See logging on page 5-78 in the Command Reference for a detailed description 
of this command. 

Logging User Comments 

It is possible for RISCWatch users to enter their own comments into the current 
log file. To do so, either the log command or Log Comment window is used. The 
log command keyword is entered on the command line of the Main window 
followed by the text to be entered in the log file. See log on page 5-77 in the 
Command Reference for a detailed description. 

The Log Comment window, shown in Figure 3-47 below, is displayed by using the 
Utilities|Logging|Comment pulldown of the Main window menubar. 



Figure 3-52. Sample Log Comment Window 
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Type the text to be entered in the log file in the edit field and then press the Enter 
key. Select the Hide button to remove this window from the screen. Select the 
Help button to bring up help information for this window. 

Screen Capture 

The contents of certain data intensive windows may be saved to an ASCII file 
using the capture command. This command allows significant amounts of 
information to be saved so that it may be viewed later or for several samples to be 
taken to be used for comparison purposes. 

When the capture command is used, the desired window is specified and the 
contents are captured to a file. If no file is specified, the contents will be saved to a 
file named rwppc.cap. To override this name, a filename is specified with the 
capture options. 

The contents of the capture file will contain a time and date stamp for each 
capture that is requested along with a description of the window captured followed 
by the appropriate window data. 

See capture on page 5-27 in the Command Reference for a detailed description 
and a list of available options. 

Calculator Window 

The Calculator window is used to mimic the operations of a basic arithmetic 
calculator. 
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Figure 3-53. Sample Calculator Window 

The calculator will run in either decimal or hexadecimal modes. Use the DEC and 
HEX buttons to switch the current mode. 
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When in DEC mode, the AND, OR, NOT, A, B, C, D, E, and F buttons will not 
function. When in HEX mode, the CHS button will not function. 

To convert a number between the two modes, simply enter the mode that the 
number is to be entered in, enter the number and then click on the alternate mode 
button which will convert the number and then display its value. 

• The mathematical operations available are: 

+ ^addition 
- = subtraction 
* = multiplication 
/ = division 
CHS = change sign 

• The bitwise operations available are: 

AND = bitwise AND 
OR = bitwise OR 
NOT = one's complement 
ASL = arithmetic shift left 
ASR = arithmetic shift right 

• Memory buttons: 

M+ = add value in display to memory value 
M- = subtract value in display from memory value 
MR = recall the memory value to the display 
MC = clear the memory value to 0 

• Other buttons: 

AC = all-clear - clears the value in the display and current calculation 
C = clear - clears the value in the display 

= = computes the value of the previously entered number with the value in 
the display using the previously specified operator 
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Online Help 

RISCWatch provides extensive online help. Most windows contain a Help button 
which provides a detailed description of the window's features. 

Using the Help pulldown of the Main window, it is possible to display help 
information for the following topics: 

• The RISCWatch program version number 

• Frequently Asked Questions (FAQ) 

The Help pull down from the Main window also provides selections for direct links 
into online documents: 

• RISCWatch Install Guide 

• RISCWatch User’s Guide 

• RISCWatch PowerPC Manuals 

The online documents are contained on the CD-ROM provided with RISCWatch 
and are in PDF format. For successful display of these documents, the following 
setup must be performed: 

• The host machine must have Adobe Acrobat Reader installed. A version of 
Acrobat Reader is provided on the CD-ROM with installation instructions. 

• The RISCWatch search path must contain the path for the “acroread” 
program provided with AcrobatReader. 

• The RISCWatch search path must contain the path for the “rw_ig.pdf” file. 
This is the name of the install guide PDF file and is provided on the 
CD-ROM. 

• The RISCWatch search path must contain the path for the “rw_um.pdf file. 
This is the name of the user’s guide PDF file and is provided on the 
CD-ROM. 

• The RISCWatch search path must contain the path for the “contents.pdf”. 
This is the name of the PowerPC Manual PDF file and is provided on the 
CD-ROM. 

Note: RISCWatch will display an error message if any of these files cannot be 
found. 

Since the help viewer invoked varies depending on the host platform and option 
selected, the instructions for using that particular viewer must be viewed online. 
Once a help window is displayed, access the Help selection of the window’s 
menubar to obtain additional information about the viewer being used. 
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Chapter 4. Using Processor-Specific Debug Features 

This chapter provides detailed information about RISCWatch features applicable 
to specific PowerPC processors or families of processors. Individual processor 
implementations within the PowerPC architecture may vary in terms of internal 
register types, cache size and organization, availability of a memory management 
unit, and other hardware functions. The RISCWatch windows in this chapter 
support these implementation-specific functions. 

Table 4-1 summarizes the features of the RISCWatch Debugger presented in this 
chapter, along with the applicability of each feature or window to specific PowerPC 
processors or processor families: 

Table 4-1. Quick Reference for Processor-Specific Debug Features 
Task or Resource Applicable Sections 


Managing Hardware Breakpoints “Using RISCTrace (400Series JTAG Processor Probe Only)” 

command on page 5-2 

“Trigger/Trace Window (400Series Only)” command on page 
5-7 

“Compound Trigger/Trace Window (401,403 Series Only)” 
command on page 5-12 

Memory Resources “Translation Lookaside Buffer Window (Applicable Proces¬ 

sors Only)” command on page 5-15 


PowerPC 400Series MMU Implementation Notes 

RISCWatch support for the Memory Management Unit (MMU) of the 400Series 
processors is subject to adherence to the following conditions: 

1. The translation mode for Data and Instruction access must be the same. 
They can both be enabled or disabled; having only one enabled is not sup¬ 
ported. 

2. If program execution is stopped at a point where the translation mode has 
changed from the state existing upon the initial file load, then the mapping 
must be real = virtual. If this is not the case, the source level debug informa¬ 
tion for the stopped context will not be displayed correctly. 

3. The real addresses in the TLB entries are assumed to be correct and valid 
addresses. 

Actions performed via the TLB window, described in “Translation Lookaside Buffer 
Window (Applicable Processors Only)” command on page 5-15, or within the 
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program itself that cause nonconformance to these conditions will produce 
unpredictable results. 

Refer to the PPC403GC/GCX Embedded Controller User's Guide in “Related IBM 
Publications” on page xxiv for more information regarding the operating 
characteristics of the MMU. 


Managing Hardware Breakpoints and Trace Events 

See “Using Hardware Breakpoints” command on page 5-72 for a general 
discussion of hardware breakpoints in RISCWatch. 

Using RISCTrace (400Series JTAG Processor Probe Only) 

Certain PowerPC 400Series processors provide a real-time trace debug mode 
which supports tracing the instruction stream being executed out of the instruction 
cache in real time. This mode does not affect the performance of the processor. 

RISCWatch provides a mechanism to utilize the hardware trace capabilities of the 
chip and gather a nonintrusive reconstruction of the flow of executing processor 
instructions. This feature of RISCWatch is known as RISCTrace. RISCTrace 
collects trace information from the trace status port in real-time and then 
reconstructs the flow of the code using the collected information and the contents 
of processor memory or program files. 

Note: The memory state will not be reconstructed, since this 
information is not included in the trace data recorded by the processor. 

Note: This is an instruction trace only; RISCTrace does not capture 
the contents of registers or memory. 

RISCTrace requires a JTAG Ethernet processor probe target which has trace 
capabilities. The RISCWatch controls for RISCTrace appear only if RISCWatch 
detects that it is connected to a processor probe which supports trace and a 
PowerPC 400Series chip which supports trace. 

When trace is supported, the Trigger/Trace and Compound Trigger/Trace windows 
provide the RISCTrace controls necessary to define and manage trace collection. 
From these windows the user can define the events which initiate the trace 
collection, and other trace parameters such as the number of cycles to trace. 
Refer to the Trigger/Trace window descriptions which follow in this section for a 
detailed description of the controls on these windows. 

After the trace parameters are specified, the Run Trace button can be used to 
start the processor running and initiate trace collection. When a specified trace is 
complete, RISCTrace automatically stops the processor, collects the trace 
information and reconstructs and formats it. This is true if the Autostop checkbox 
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is enabled. If the Autostop checkbox is disabled, RISCTrace will only indicate that 
the trace is complete. When the user stops the processor, RISCTrace then 
collects the trace information and reconstructs and formats it. The formatted trace 
is saved in the file rwppc.trc and displayed in a view window (see the “view” 
command on page 5-147 for details on using this window). The Save Trace button 
can be used to save the formatted trace in a file of your choice, as well as allowing 
you to enter optional comment lines which are appended to the beginning of the 
formatted trace information in the saved file. 

Selecting the Stop Trace button while a trace is running causes the trace which is 
currently running to be aborted. The abort results in the processor being stopped 
with no trace reconstruction occurring for the trace which was running. However, if 
the trace is complete, the trace is collected, reconstructed and formatted. The 
Stop Trace button is useful when Autostop mode is disabled. 

If it is not desired to have any program symbol information included in the trace 
output, the unload all command can be used to unload all the program 
information from RISCWatch prior to initiating the trace. This also speeds up the 
trace reconstruction. A detailed description of the trace output follows in the 
‘RISCTrace Output’ section below. 

For additional information on processor-supported trace, consult the appropriate 
chip user’s manual. 

RISCTrace Operational Notes 

1. RISCTrace uses the IOCR[RDM] bits (bits 26-27 of the IOCR register) to col¬ 
lect a trace. RISCTrace cannot properly trace code that modifies these bits. 
Also, if bits other than the RDM bits are to be changed by the application 
code, a read/modify/write operation is recommended. Note that the 
IOCR[RDM] field is 403 specific and does not necessarily apply to other 
400Series processors. 

2. If the IOCR[RDM] bits are set to bus status mode and a logic analyzer disas¬ 
sembler (aka inverse assembler) is hooked up to the processor, using RISC¬ 
Trace to collect a trace will change the IOCR[RDM] bits from bus status mode 
to trace mode, collect the trace, then restore the bits to bus status mode. This 
operation may affect the operation of the logic analyzer disassembler. Note 
that the IOCR[RDM] field is 403 specific and does not necessarily apply to 
other 400Series processors. 

3. RISCTrace uses debug events to collect a trace. Thus, RISCTrace cannot 
trace code that clears the DBSR because clearing this register also clears all 
debug events. 
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4. 


On the 403GCX, the RISCTrace pins are multiplexed with the new parity pins. 
If the IOCR[RDM] bits are set to parity mode, RISCTrace will not collect a 
trace. Pressing the run trace button will result in an error message. Also, 
RISCTrace cannot collect a trace from a clock doubled 403GCX unless the 
enhanced JTAG adapter assembly with RISCTrace is used (see the install 
guide for descriptions of the different adapters). 

5. Known causes for a run trace failure are: 

• Wrong transfer adapter connected to the front of the RISCWatch 
processor probe. The special adapter that is shipped with the 
RISCWatch processor probe with RISCTrace must be used. 

• Invalid cycle count specified on the trace window (see “RISCTrace 
Controls” command on page 5-10). 

• Trace port used for parity generation (403GCX only). 

• CPU is clock doubled (403GCX only) and an older version RISCTrace 
Processor Probe (maximum 64K cycle trace buffer) is being used. The 
new RISCTrace Processor Probe unit, with 500K cycle instruction trace 
capability, should be used. 

6. RISCTrace writes the reconstructed code to a file in the directory from which 
RISCWatch was started. These files may be in excess of lOOMbytes. 

RISCTrace Output 

The output file resulting from a successful trace contains various elements of 
information which are presented in a consistent manner for each trace. 
Guaranteeing that key information is presented in a consistent manner allows 
users the flexibility to write their own post-processing routines which can operate 
on the trace output file. 

The trace output file format is currently at version 2.0 and hence is different from 
the example shown on the following pages. Please run a trace with the latest 
version of RISCWatch and view the output stored in the file rwppc.trc. 
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# RISCTrace : Trace Output File Version 2.0 

# DATE : Sun Aug 20 06:03:04 2000 

# TRACE TRIGGER SETTINGS : IAC1 occurring 1 time 

#Instr Total Cycle/ (function 

# Count Cycle Instr Address offsets) Opcode Disassembly 

# . - - - - - - 


$ FUNCTION: main START_ADDR: 0x0000A078 FILE: demol.c PROGRAM: ./demo 
0000001 0000000 0000A0A0(+000028) 90610040 stw R3,0x00000040(Rl) 

# 0000000 ** STATUS: Trigger event ** 

0000002 0000002 0000002 0000A0A4(+00002C) 38600003 addi R3,0,0x0003 

0000003 0000004 0000002 0000A0A8(+000030) 90610050 stw R3,0x00000050(Rl) 

*** Entries removed for figure display purposes *** 


$ FUNCTION: routined START_ADDR: 0x0000A180 FILE: demol.c PROGRAM: ./demo 
0000062 0000214 0000011 0000A180(+000000) 9421FFC0 stwu Rl,0xFFFFFFC0(Rl) 

0000063 0000216 0000002 0000A184(+000004) 90610058 stw R3,0x00000058(Rl) 

*** Entries removed for figure display purposes *** 

0000073 0000253 0000002 0000A1 AC(+00002C) 30210040 addic R1,R 1,0x0040 
0000074 0000267 0000014 0000AlB0(+000030) 4E800020 blr 


$ FUNCTION: main START_ADDR: 0x0000A078 FILE: demol.c PROGRAM: /sld/rwppc/regress/src/demo 
0000075 0000269 0000002 0000A0F8(+000080) 48000121 bl $+0x00000120 


$ FUNCTION: routine2 START_ADDR: 0x0000A218 FILE: demo2.c PROGRAM:/sld/rwppc/regress/src/demo 
0000076 0000280 0000011 0000A218(+000000) 7C0802A6 mflr R0 

*** Entries removed for figure display purposes *** 

0000121 0000505 0000011 0000A290(+000008) 800C0000 lwz R0,0x00000000(R12) 

0000122 0000507 0000002 0000A294(+00000C) 804C0004 lwz R2,0x00000004(R12) 

# 00000000 ** Interrupt detected ** 

$ FUNCTION: ? START_ADDR: ? FILE: ? PROGRAM: ./demo 
0000125 0000543 0000032 FFFE0700 7C0004ACsync 

0000126 0000559 0000016 FFFE0704 90200034 stw R 1,0x00000034(0) 

000127 0000575 0000016 FFFE0708 90400038 stw R2,0x00000038(0) 


Figure 4-1. Sample Trace Output File 
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The following general rules hold true for any trace output file, such as the sample 
in Figure 4-1: 


1. All comments are preceded by the comment character '#’ 


These may be separate comment lines, or comments at the end of trace 
entries. 


2. If comment lines are added to the trace via the Save Trace window, they are 
the first lines in the file and preceded by the comment character '#’ 

3. A comment line containing the words ‘RISCTrace : Trace Output File’ either 
follows the optional comment lines (if they exist) or is the first line in the file. 

4. A comment line containing the information ‘DATE : timejnfo’ follows next, 
where timejnfo is the time/date information in the format defined by the ANSI 
ctime() function. 

5. A comment line containing the information TRACE TRIGGER SETTINGS 
trigger settings’ follows, where trigger_settings describes the trigger settings 
at the time the trace was collected and in the format shown at the top of the 
Compound Trigger/Trace window. 

6. The trace header (preceded by the comment character *#’) follows: 

#Instr Total Cycle/ (function 

#Count Cycle Instr Address offsets) Opcode Disassembly 


7. The trace entries follow next. Each field of the entry is aligned below the field 
name in the header, as described below: 


Instr Count 
Total Cycle 
Cycle/lnstr 

Address 

Opcode 


The sequential entry number within the trace output. 

The running count of cycles for the trace. 

The number of cycles for this executed instruction. This field 
provides a quick way to determine which instructions in the 
trace are taking the most cycles to execute. 

The address of this executed instruction. This may include 
an offset in () from the beginning of the function if program 
symbol information is available 

The hex opcode for this instruction executed. 


Disassembly The disassembled Opcode value. 


The first three columns of data are displayed in decimal format while the last 
three are always hexadecimal (whether preceded by ‘Ox’ or not). 
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8. If program information is loaded corresponding to a trace instruction address, 
a program information entry preceded by the special character '$’ appears 
before the first instruction of each new function entry point as it is encoun¬ 
tered in the trace. 

The format of the program information entry is as follows: 

FUNCTION: func START_ADDR: start_addr FILE: file PROGRAM: prog 
Where: 

func function name ,'?’ if unknown 

start_addr start address for the function, “?’ if unknown 
file file containing the function ,'?’ if unknown 

prog fully qualified program name ,'?’ if unknown 

If the trace execution flow goes from an instruction which has program 
information associated with it, to one with no program information, all the 
fields above are 

9. A blank line appears between trace entries where a break in sequentially exe¬ 
cuted instruction addresses (for example, a branch to another area of the pro¬ 
gram) occurs. 

Trigger/Trace Window (400Series Only) 

The Trigger/Trace window is used to manage hardware breakpoints and trace 
events. Breakpoints managed by this window are accessible by using the built-in 
debug functions of the processor. Hardware breakpoints are not available for OS 
Open targets. An explanation of trace capabilities is explained in “Using 
RISCTrace (400Series JTAG Processor Probe Only)” command on page 5-2. 
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Trigger/Trace 


□ Branch Taken 
W Inst Address(1> 
W Inst Address(3> 
J 112 Range Enable 

W Bata Address(1> 


00000000 


00000000 


T 


00000000 


J Exception 
W Inst Address!2) 
W Inst Address!4> 
J 134 Range Enable 

Data Address!2> 


00000000 


00000000 


00000000 


R/W 


*1 


D12 Range Enable 
Data Val Cmp(l) 


Read 

*1 


Inc 

T 


Ignore 2 


*l 


00000000 


Data Val Cmp!2) 


00000000 


Byte 1,2,3 J 


All bytes 


Debug mode : 


J External 


_J Internal 


RISCTrace Controls: 
Cycles Before Trigger = 


0000100 


Total Cycles Allowed 
Cycles After Trigger = 


W Autostop W From Mem 
Run Trace | Stop Trace | Save Trace | 


Hide 


Help 


Figure 4-2. Sample Trigger/Trace Window with Trace Supported 

• Branch Taken event 

The Branch Taken event trigger is enabled and disabled according to the state of 
its check box. If the check box is enabled, the trigger is enabled too. 

• Exception event 

The Exception event trigger is enabled and disabled according to the state of its 
check box. If the check box is enabled, the trigger is enabled too. 

• Instruction Address Compare events 

An Instruction Address Compare event trigger is enabled and disabled according 
to the state of its check box. If the check box is enabled, the trigger is enabled too. 
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If an Instruction Address Compare is enabled, the appropriate address to trigger 
on should be entered in the address field. Use the mouse to place the edit cursor 
in the appropriate address field, enter a new hexadecimal value and then press 
the Enter key. 

• Instruction Address Range events 

Instruction address range events are enabled and disabled according to the state 
of the Instruction Range Enable check boxes. These selections are enabled only 
when the corresponding Instruction Address check boxes have been selected. For 
example, the 112 Range Enable checkbox would be enabled only if the Inst 
Address(l) and Inst Address(2) check boxes were already selected. The range 
specified can either be inclusive (Inc), inclusive toggle (Inct), exclusive (Exc) or 
exclusive toggle (Exct) to the values specified in the Inst Address data fields. 

The toggle ranges are used to automaticaly toggle between ranges each time the 
processor stops for the specified range. For example, if inclusive toggle is enabled 
and the processor stops in the specified range, the toggle will switch to exclusive 
mode. If the processor is run and then stops in the exclusive range, the toggle will 
again occur and return to inclusive mode. 

The toggle ranges are only available on some 400Series processors. 

• Data Address Compare events 

A Data Address Compare event trigger is enabled and disabled according to the 
state of its Data Address check box. If a check box is enabled, the trigger is 
enabled for that event. 

If a Data Address Compare is enabled, the appropriate address to trigger on 
should be entered in the address field. Use the mouse to place the edit cursor in 
the appropriate address field, enter a new hexadecimal value and then press the 
Enter key. 

For the Data Address Compare events, a trigger may be generated for a read 
and/or write to the specified address. Enable the desired event(s) by selecting the 
desired mode in the corresponding list box. The list box entries are displayed by 
using the mouse to place the edit cursor on the triangle next to the selection and 
pressing the left mouse button. The option is then selected by clicking on the 
desired selection. The Data Address Compare events also allow for masking of 
the data address on compares through the use of the corresponding list button to 
the right of the mode selection. The masking size is once again selected by using 
the triangle to display the possible options and clicking on the desired entry. 

• Data Address Range events 

Data address range breakpoints are enabled and disabled according to the state 
of the Data Range Enable check box. These selections are enabled only when 
both of the Data Address check boxes have been selected. The range specified 
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can either be inclusive (Inc) or exclusive (Exc) to the values specified in the Data 
Address Compare data fields. 

• Data Value Compare events 

A Data Value Compare event trigger is enabled and disabled according to the 
state of its Data Val Cmp check box. If a check box is enabled, the trigger is 
enabled for that event. 

If a Data Value Compare is enabled, the appropriate data to be used for the 
compare should be entered in the data field to the right of the check box. Use the 
mouse to place the edit cursor in the appropriate data field, enter a new 
hexadecimal value and then press the Enter key. 

Next, the compare conditions must be specified by indicating which bytes are to 
be compared, and how they are to be compared. This is accomplished by 
selecting the desired options in the list boxes shown directly under the 
corresponding Data Val Cmp check box. 

Note that a Data Value Compare can only be enabled when the corresponding 
Data Address compare event has previously been enabled. 

• Debug mode 

The Debug mode check boxes are used to select the debug mode under which 
the processor will be running which in turn dictates the action to be taken when an 
event is triggered. Select the External check box to run in External Debug mode. 
Select the Internal check box to run in Internal Debug mode. In External Debug 
mode, when a debug event is detected the processor will be stopped. In Internal 
Debug mode, when a debug event is detected, the processor will vector to the 
appropriate exception handler for processing. 

Note: For normal exception-driven processing of Data or Instruction 
Address breakpoints by a ROM Monitor or OS Open target, Internal 
debug mode should be selected. 

For additional information on these and other processor debug features, consult 
the Debugging chapter of the User’s Manual for the specific PowerPC 400Series 
processor being used. Not all features shown above are supported across all 400 
Series processors. 

RISCTrace Controls 

RISCTrace controls appear on the window only if RISCWatch determines that 
trace is supported. Refer to “Using RISCTrace (400Series JTAG Processor Probe 
Only)” command on page 5-2 for an explanation of RISCTrace. When a trace is 
running, the trigger events described above define when the trace is triggered. 
The following controls are specific to RISCTrace: 

• Cycle count specification 
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The 400Series processor which RISCWatch is attached to may support either a 
‘forward only’ trace (where tracing begins only after the specified trigger event 
occurs) or a ‘backtrace’ capability (where a ‘window’ of cycles around the trigger 
event may be specified). 

If the processor supports a ‘forward only' trace, the ‘Cycles Before Trigger’ count 
(the count of cycles before the trigger event occurs) is always zero and cannot be 
altered. The ‘Cycles After Trigger’ count (the count of cycles following the trigger 
event) can be adjusted with a value not exceeding the maximum size of the trace. 

If the processor supports a ‘backtrace’ capability, the ‘Cycles Before Trigger’ count 
and the ‘Cycles After Trigger’ count can both be adjusted to define a ‘window’ of 
cycles around the trigger event, with the total of the two not exceeding the 
maximum size of the trace. 

Use the ‘Total Cycles Allowed’ field value to help you select suitable values for the 
before and/or after trigger counts. 

In both cases, if the total of the two is below a certain minimum, the ‘Cycles After 
Trigger’ will be rounded up to this minimum. 

• Run Trace button 

After the trigger event(s) and cycle count(s) are specified, the Run Trace button 
starts the processor running and initiates trace collection. When a specified 
trigger event occurs, RISCTrace automatically collects the trace information and 
reconstructs and formats it. The formatted trace is saved in the file rwppc.trc and 
displayed in a view window (see the “view” command on page 5-147 for details on 
using this window). 

• Stop Trace button 

Selecting the Stop Trace button while a trace is running causes the trace which is 
currently running to be aborted. The abort results in the processor being stopped 
with no trace reconstruction occurring for the trace which was running. However, if 
the trace is complete, the trace is collected, reconstructed and formatted. The 
Stop Trace button is useful when Autostop mode is disabled. 

• Save Trace button 

The Save Trace button can be used to save the formatted trace in a file of your 
choice, as well as allowing you to enter optional comment lines appended to the 
beginning of the formatted trace information in the saved file. 

• Autostop checkbox 

Enabling the autostop checkbox makes RISCTrace automatically stop the 
processor, collect the trace and then reconstruct and format it when the specified 
trace is complete. 
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Disabling the autostop checkbox makes RISCTrace only indicate that the specified 
trace is complete. Using the Stop Trace button will then stop the processor, collect 
the trace and then reconstruct and format it. 

• From Mem checkbox 

Enabling the From Mem checkbox informs the RISCTrace reconstruction software 
to use the contents of memory on the user’s target during the reconstruction 
process. 

Disabling the From Mem checkbox informs the RISCTrace reconstruction software 
to use the program files that were previously loaded with the RISCWatch load 
command during the reconstruction process. Any address required by the 
reconstruction process and not found in the program files is read from memory on 
the user’s target. 

Compound Trigger/Trace Window (401, 403 Series Only) 

The Compound Trigger/Trace window is available on those processors which 
support compound debug events.This window is very similar to the Trigger window 
with some additional features to make use of compound debug event functionality. 
Refer to “Trigger/Trace Window (400Series Only)” command on page 5-7 for an 
understanding of the basic features this window provides and to “Using 
RISCTrace (400Series JTAG Processor Probe Only)” command on page 5-2 for 
the control information provided with RISCTrace. 
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Figure 4-3. Sample Compound Trigger/Trace Window with Trace Supported 
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Using the Compound Trigger/Trace window, three classes of triggers may be set 
up: 

1. Trigger on one or more events 

2. Trigger after one or more events occurs a specified number of times 

3. Trigger after one or more events occurs a specified number of times which is 
followed by a single occurrence of one or more events. 

Available debug events include: 

1. Branch taken 

2. Exception 

3. Instruction address compare 

4. Data address compare 

The initial trigger events are selected using the check boxes under the “Trigger on 
events” heading. These check boxes are the same as those found in the Trigger 
window. One or more of these events may be specified. As events are selected, 
notice the text appearing in the “Trigger on” field at the top of the window. 

If it is desired, an event occurrence counter may be set using the text field at the 
top of the window. Enter the desired count into the box and press Enter. 

Once a Trigger on event is specified, several ’’followed by” events are available for 
use as check boxes under the “Followed by events” heading. If an event is 
selected as a Trigger-on event, it is not available for use as a Followed by event 
and vice versa. As Followed by events are selected, notice the text appearing in 
the “followed by” field at the top of the window. 

The Instruction and Data address controls at the bottom of the window can only 
be accessed if the appropriate event has been selected as a “Trigger on” or 
“followed by” event. 

The Debug mode check boxes are used to select the debug mode under which 
the processor is running which in turn dictates the action to be taken when an 
event is triggered. Select the External check box to run in External Debug mode. 
Select the Internal check box to run in Internal Debug mode. In External Debug 
mode, when a debug event is detected the processor is stopped. In Internal 
Debug mode, when a debug event is detected, the processor vectors to the 
appropriate exception handler for processing. 

Note: For normal exception-driven processing of Data or Instruction 
Address breakpoints by a ROM Monitor or OS Open target, Internal 
debug mode should be selected. Flardware breakpoints are not 
available for OS Open targets. 
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RISCTrace controls appear on the window only if RISCWatch determines that 
trace is supported. See“RISCTrace Controls” command on page 5-10 for further 
information. 


Memory Resources 

See “Reading and Writing Memory” command on page 5-104 for a general 
description of RISCWatch features and windows for memory access. 

Translation Lookaside Buffer Window (Applicable Processors Only) 

The TLB window is used to read and write entries in the Translation Lookaside 
Buffer (TLB) of a processor which contains a Memory Management Unit (MMU). 
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Figure 4-4. Sample TLB Window 


“PowerPC 400Series MMU Implementation Notes” command on page 5-1 
provides details affecting RISCWatch support for PPC403GC/GCX TLB 
operations. Additionally, for OS Open targets, the TLB window is only functional 
with OS Open version 1.6 or later and is not available for OS Open with Virtual 
Memory targets. 

This window is displayed by selecting the Memory | TLB option of the menubar’s 
Hardware pulldown choice. Along the left hand side of the window are the TLB 
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entry numbers. To the right is the data area, where the contents of the TLB are 
shown . 


The scroll bar located on the right side of the data area can be used to show 
entries that do not fit in the window display. Alternatively, the window can be 
resized to show the desired number of entries. 

The labels across the top of the data window are used to help identify the 
quantities being displayed for the TLB entries. The labels are: 

EPN effective page number 

S page size 

V valid bit 

T TID 

RPN real page number 

Z ZSEL field value 

W WIMG bits (Write-through, Inhibit, Memory coherence, Guarded) 

E EXecute bit 

WR WRite bit 

Note: Page numbers (EPN & RPN) are always displayed normalized 
to bit 0 (MSB). WIMG bits are displayed as a hexadecimal value with 
bit positions, from left to right, being W, I, M, and G. 

The Read button is used to force a read of the processor TLB data to display the 
latest contents. 

The Close button is used to remove this window from the screen. 


Processor Resources 

See “Processor Reset Window (JTAG Targets Only)” command on page 5-138 for 
a description of RISCWatch options for resetting a PowerPC processor. 
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Chapter 5. Debugger Command Reference 

This chapter describes the RISCWatch Debugger commands. These commands 
can be entered on the command line of the Main window of the graphical user 
Interface. 

The commands are listed in alphabetical order. Each command description 
contains the following sections: 

• Name 

• Syntax 

• Description 

Some command descriptions contain one or more of the following sections: 

• Flags 

• Examples 

• Related Information 


Processors Currently Supported 

The RISCWatch Debugger supports numerous PowerPC processors and 
versions. For more information on current processors supported and other up to 
date information, please refer to the README file included with the product, or 
visit our web site at http://www.chips.ibm.com/products/embedded/riscwtch 

Support for additional PowerPC processors and targets is planned for future 
RISCWatch releases. 


Reading the Syntax Diagrams 

See “Syntax Diagram Conventions” on page xxiii for detailed information about 
the conventions used in the RISCWatch Debugger command syntax diagrams. 


Using RISCWatch Debugger Commands 

Commands and keywords are not case sensitive. You may enter commands using 
either uppercase or lowercase characters. File names and variable names are 
typically case sensitive and should be entered in lower case or as shown in the 
individual command descriptions. 
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Each command description provides a table to summarize the processors, 
modes, hosts, and targets with which that command can be used. The 
combination of processors, targets (JTAG, OS Open, or ROM Monitor), and usage 
modes applicable to each command are indicated by bullets (•) in the appropriate 
table cells. Notes below the tables provide additional details of command 
applicability. 

A sample environment table is shown below: 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 
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Window Quick Reference 

window window name, specified by one of the following keywords: 


ascii 

asic 

‘breakpoint 

‘cache 

calculator 

‘callers 

cfss 

coherency 

ctrigger 

‘dcache 

dor 

debug 

dtlb 

‘files 

fpr 

‘functions 

‘globals 

gpr 

‘icache 

‘inspect 

itlb 

*12 

‘locals 

log 

‘osopen 

output 

‘programs 

reset 

regfld 

rf cache 

rfconfig 

rfdbat 

rfdbg 

rfdmaO 

rfdmal 

rfdma2 

rfdma3 

rfdram 

rffprO 


ASCII Memory window 
ASIC register window 
Breakpoints window 
Cache (unified) window 
Calculator window 
Callers window 

Command File Single Step window 
Memory Coherency window 
Compound Trigger Trace window 
Data Cache window 
Device Control Registers window 
Assembly Debug window 
Data Translation Lookaside Buffer window 
Files window 

Floating Point Registers window 
Functions window 
Globals window 

General Purpose Registers window 

Instruction Cache window 

Variable Inspect window 

Instruction Translation Lookaside Buffer window 

L2 Cache window 

Locals window 

Log Comment window 

OS Open window 

Output window 

Programs window 

Processor Reset window 

Single register field 

Fields for Cache Registers 

Fields for Configuration Registers 

Fields for 6xx DBAT Reg Fields 

Fields for Debug Registers 

Fields for DMAO Registers 

Fields for DMA1 Registers 

Fields for DMA 2 Registers 

Fields for DMA 3 Registers 

Fields for DRAM Registers 

Fields for FPRs 0-7 
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rffprl 

Fields for FPRs 8-15 

rffpr2 

Fields for FPRs 16-23 

rffpr3 

Fields for FPRs 24-31 

rfibat 

Fields for 6xx IBAT Reg Fields 

rfmem 

Fields for Memory Protection Registers 

rfmmu 

Fields for 6xx MMU Regs 

rfpm 

Fields for Performance Monitor Regs 

rfsr 

Fields for 6xx Segment Reg Fields 

rfsram 

Fields for SRAM Registers 

rftimr 

Fields for Timer Registers 

‘source 

Source window 

spr 

Special Purpose Registers window 

tlb 

Translation Lookaside Buffer window 

trigger 

Trigger Trace window 

udw 

User Defined window 

‘varcfg 

Variable Configuration window 

winlist 

Window list 


* Applies to commands using both the window and pane keyword (except for 
window command). 

Note: Not all windows are applicable to all target processors and hosts. 

Command Quick Reference 


The following is a list of commands and the syntax of each command. For further 
details, see the syntax and description sections in the individual command 
reference pages which follow this quick reference. 

The following identifiers are used to improve readability : 


address 

int_var 

field_name 

fld_var 

float 

flt_var 

imm_var 

instance 


an optional item 

a selection between two or more items 

any valid memory address value (usually specified as a 32 bit 
hex number) 

any integer variable created with the create command 

an appropriate register field name as it appears in a Register 
Field window, or bit number 

any register field variable created with the assign command 
any valid floating point number 

any float variable created with the assign or create command 
any immediate variable created with the assign command 
a register or window instance number 
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mem_var 

mpsjd 

pane 

bpset 

bpunset 

cachedata 

cacheword 

varinvis 

varvis 

reg_class 


reg_name 

reg_pre 


reg_var 
src var 


str_var 

value 


any memory variable created with the assign command 

valid MPS chip or device name from MPS file 

window pane name, specified by one of the following keywords: 

Breakpoint Select window, window showing functions with 
bp set 

Breakpoint Select window, window showing functions with 
bp not set 

Cache window, window showing data/tag entries 
Cache window, window showing word entries 
Variable Config window, window showing invisible vars 
Variable Config window, window showing visible vars 
any valid processor register class (DCR, GPR, etc.) The list of 
valid classes may be found by accessing the program menu bar 
under Hardware | Register. The keyword ALL is always a valid 
class. 

any valid processor register name 

any valid ASIC register prefix. If the chip you are debugging has 
any ASIC registers defined, the list of valid prefixes may be 
found by accessing the program menu bar under Hardware | 
Register | ASICs. 

any register variable created with the assign command 

any valid local or global source variable name that is currently in 
scope. The name must be preceded by a colon See “Source 
Variable Command Support” on page 3-103 for further 
information. 

any string variable created with the assign or create command 
any decimal, octal or hexadecimal value 


Table 5-1 summarizes the syntax of the RISCWatch Debugger commands: 


Table 5-1. Syntax Summary for Debugger Commands 

Command 

Parameters 

asmstep 

[value] 


Debugger Command Reference 


5-5 





Table 5-1. Syntax Summary for Debugger Commands 


Command 

Parameters 


fld_var = reg_name.field_name 


imm_var = value 

assign 

mem_var = (address) 

flt_var = float 


reg_var = reg_name 


str_var = “string” 

assm 

"assembly" [address[int_var|reg_name|reg_var] 

attach 

threadid 

beep 

[off |on] 

bot 

[window [pane]] 


set [dacr|dacw|dacrw] address [dac_reg] [cmp_size] 


set dvc dvc_reg [comp_bytes] [comp_mode] 


set ihw address [iac_reg] 


set [ihw] at src_file:line_num 


set [ihw] in [“]function[“] 

bp 

set range [inc|inct|exc|exct] range_reg1 range_reg2 


clear address|all iac_reg 


clear [dacr|dacw] address 


clear at file_name:line_num 


clear in [“]function[“] 


clear range [inc|exc] range_reg1 range_reg2 

bpmode 

[hw [step]|hardware [step]]|[sw|software] 

callstep 

capture 

window[reg_pre]|pane|all [total] [filename] 
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Table 5-1. Syntax Summary for Debugger Commands 


Command 

Parameters 

cfss 

sp set|clear at file_name:line_num 


sp set|clear at line_num 


sp clear all 

color 

[reset | [cbak|cfore|tback|tfore|wback|wfore color]] 

config 

drtry|parity|32bitmode [on|off] 

create 

flt_var = float 


int_var [= value] 


str_var = “string” 

delay 

value imm_var int_var 

detach 

dis 

value|(address)|int_var|mem_var|reg_name|reg_var 

down 

[lines [window [pane]]] 

end 

[all] 

exec 

command_file[[variable_list}] [step] 

expr 

expression 


append|new filename 

fctrl 

close 


errors|log|status on|off 

file 

[filename] 

find 

[[string [window [pane]]] | [$last$ window [pane]]] 

findb 

[[string [window [pane]]] | [$last$ window [pane]]] 

finde 

[[string [window [pane]]] | [$last$ window [pane]]] 

focus 

[window [pane]] 

fold 

on|off 

fprdisp 

[hex|sci] 
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Table 5-1. Syntax Summary for Debugger Commands 


Command 

Parameters 

fprint 

print_string 

freeze 

never|stop|always 

funcdisp 

[all_addr|all_name|dbg_addr|dbg_name] 

goto 

value|label|[addr address]|[line file_name:line_num] 

halt 

[on |off] 

hidewins 

ip 

jtag 

clock [value] 

killthread 

line 

[value [window [pane]]] 

linestep 

[value] 


binary bin filename address int__var imm_var 


dmem imem filename [address int_var imm_var] 


file filename [d=address] [s=address|ss=size] [t=address] [nosym] 


host filename [d=address] [s=address|ss=size] [t=address] [nosym] 

load 

hp filename 

image filename 


layout filename 


motorola mot filename 


reg filename 


tektronix tek filename 

log 

message 

logging 

[on |off] 

logoff 

memacc 
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Table 5-1. Syntax Summary for Debugger Commands 


Command 

Parameters 

memchk 

address [length] 

memcoh 

read mm|phys|reset 


write dmem bypass|cache|mm|reset|thru 


write imem cahce|iidb|iidu|iudb|iudu|iidf|reset 

memcopy 

source dest mm_var|int_var|length 

memfill 

address imm_var int_var value imm_var int_var value 

memfind 

address length string|value [int_var] 

memrwait 

[value] 

memwwait 

[value] 

mpsset 

mpsjd 

pagedn 

[window [pane]] 

pageup 

[window [pane]] 

parms 

[varl [, var2, varN]} 

poll 

[[id target on|off] | [run|status] value|imm_var int_var]] 

post 

string 

prefer 

src_vars type = format 

print 

print_string 

quit 

[-f] 

read 

address|mem_var|src_var|int_var|imm_var [int_var|reg_name|reg_var] 

readb 

address|mem_var|int_var|imm_var [int_var|reg_name|reg_var] 

readh 

address|mem_var|int_var|imm_var [int_var|reg__name[reg_var] 

read 

reg_name | reg_var [i nt_var| reg_name | reg_var] 

reg 

reg_class|reg_pre| 

reset 

core|chip|sys 

restart 
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Table 5-1. Syntax Summary for Debugger Commands 

Command 

Parameters 

retstep 

run 

[timeout[[to [address | file_name:line_num]]] 


reg|reginfo|regfldinfo|layout filename [reg_class|reg_pre] 

save 

mem filename address int_var imm_var bytes[int_var immvar 


bin|binary filename address|int_var|imm_var [append] 

set 

(address)|mem_yar|src_var|int_var|reg_name[.field_name|.#]|reg_var|fld_var|flt_yar|str_v 
al = expression 

shell 

expression|str_var 

showip 

socket 

timeout [value] 

srcdisp 

source| mixed 


[q[uery]] 

srchpath 

set dirl (dir2 . . . dirN) 

add dir 


c[lear] 

srcline 

[imm_var int_var line] 

startthread 

funcname [groupjd] 

stop 

[timeout] 

stuff 

opcode|"assembly"|reg_name|variable 

timer 

start|stop 

top 

[window [pane]] 

trace 

unassign 

all|fld_var|imm_var|mem_var|flt_var|reg_var|str_var 

uncreate 

all|flt_var|int_var|str_var 

unload 

all|filename 
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Table 5-1. Syntax Summary for Debugger Commands 

Command 

Parameters 

up 

[int_vat|imm_var|lines[window [pane]]] 

varinfo 

locals|globals all|none|[addr][size][type] 

varvis 

locals|globals vis|invis 

view 

[filename] 

window 

[window [reg_pre] [mps_id]] | [cfss [filename]] | [udw [mpsjd] filename] | [regfld [mpsjd] regname 
[instance]] 

write 

dmem imem address mem_var int_var imrn_var value|int_var imm_var|reg_name 

write 

src_var value int_var imm_var 

writeb 

dmem address mem_yar int_var|imm_var value int_var imm_var reg_name 

writeh 

dmem address mem_var int_var|imm_var value int_var imm_var reg_name 


Debugger Command Reference 


5-11 








asmstep 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


. asmstep 


I_ value _I 


Description 

asmstep runs the processor for the execution of one or more 4-byte machine 
instructions. 

If the value parameter is omitted, it defaults to 1. 

Flags 

value Specifies the number of machine instructions the processor is to step. 

Note for 400Series JTAG targets: If the IAR is pointing to an RFI or RFCI 
instruction, processor requirements dictated that two instruction steps be taken to 
execute these instructions. This special case is handled automatically by the 
program. 

If the debugger is in source mode and the IAR is pointing to a branch instruction 
that will be taken, the debugger context will be switched to the target of the 
branch. This has the same effect as issuing a callstep instruction. 

See Also 


• callstep on page 3-26 
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assign 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 

Syntax 


assign 


variable — = 


reg_name 


— reg_name.field 

— (address) 

—value 

— “expression" 


Description 

assign is used to assign a value to a variable name. The value can be an 
immediate value, a memory address value, a value in a register, or the value of a 
register field or expression. The name given to the variable must not start with a 
number or match any processor register name. Variable names are also case 
sensitive. 

An immediate value can be any number given in floating point, octal, decimal or 
hexadecimal form. To assign the value of a register or field, the register or register 
field name or number is specified. A memory address is specified as an 
immediate value enclosed by the '(' and ')' characters to differentiate it from an 
immediate value. 

Having assigned a value to a variable name, the variable name can be used in 
commands that accept fld_var, flt_var, imm_var, mem_var, or str_val as valid input 
parameters. See Table 5-1 for a command syntax summary that shows which 
commands accept assign variables as parameters. 
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assign 


Flags 


value 

An initial data value 

“expression” 

An expression, enclosed in double quotes, that is 
placed into the variable 

(address) 

The memory address assigned to the variable. Note 
that the () characters are used to distinguish a memory 
address from an immediate value. 

reg_name 

The name of the register assigned to the variable. 

reg_name.field 

The register name concatenated with the field name or 
bit number assigned to the variable. 

variable 

The name given to the assigned variable so that it may 
be referenced in future commands 


Example 

• Assign a register to a variable and then uses the variable to initialize and read 
the register's value. 

assign count_reg = SPRG1 # make count_reg = SPRG1 

set count_reg =0 # init count register 

read count_reg # i.e. read SPRG1 

• Assign an immediate value to a variable which is then used to initialize the 
value of a register. 

assign reg_val = 0x11223344 
set SPRGO = reg_val 

See Also 


• create on page 3-35 

• set on page 3-117 
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assm 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

assm converts a valid assembly instruction into a 4-byte instruction value and 
then optionally writes this value to the specified register, user-created variable, or 
processor instruction memory at the specified address. 

Flags 

"assembly" A string containing a valid assembly instruction 
str_var A string variable containing a valid assembly instruction 

address The memory address to write the assembled instruction value to 

int_var Any variable created with the create command 

reg_name The name of a register to write the assembled instruction value 

to 

reg_var Any register variable created with the assign command 

Any operands that accompany an assembly instruction must consist of one 
contiguous string of characters. There can be no spaces between the operands if 
there are more than one. 
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assm 


If no memory address, register name or user-created variable is specified, the 
string will simply be assembled and the subsequent machine instruction that is 
generated will be printed out in a status message. 

Examples 

• Generate the instruction necessary to move the contents of a special purpose 
register to a general purpose register and then write the generated instruction at 
memory address 0xE0B15. 

assm "mfspr rl3,LR" 0xE0B15 

• Generate the instruction necessary to move the contents of a special purpose 
register to a general purpose register and then store the generated instruction 
in a user-created variable. 

create assm_value 

assm "mfspr rl3,LR" assm_value 

• Generate the instruction necessary to move the contents of a special purpose 
register to a general purpose register and then write the generated instruction to 
register GPR8. 

assm "mfspr rl3,LR" R8 

See Also 

• dis on page 3-39 
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attach 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 


OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 



Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 

Syntax 

attach - threadid - 


Description 

attach initializes a source mode debug session with threadid under OS Open. 
threadid must be the number of an existing thread. A list of current threads can be 
found by clicking on the "List Threads" buttons of the OS Open window. 

Note: RISCWatch cannot be used to debug the OS Open shell. 

Flags 

threadid The number of an existing thread 

Examples 

• Attach to an existing OS Open thread. 

attach 0x31568 

See Also 


• detach on page 3-38 

• kill thread on page 3-70 

• start thread on page 3-129 
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beep 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

beep controls the program beeper. It may be used to turn the program beeps on 
or off or to sound the program beeper. If the on and off parameters are omitted, it 
sounds the program beeper. 

Flags 

off 
on 

Examples 

• Turn the program beeper off 

beep off 

• Turn the program beeper on 

beep on 

• Sound the program beeper 

beep 


Turn the program beeper off 
Turn the program beeper on 
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Description 

bot scrolls to the last line of a window, highlighting the line if it contains any text. 

If the window keyword is not specified, the last window specified for this command 

is used. It initially defaults to the Source window. 

Flags 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) refer to commands using both window and pane 
keywords. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 


Examples 

• Scroll to the last line of the window previously specified by this command. 

bot 

• Scroll to the last line of the Breakpoint window. 

bot break 
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bp 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


set 


clear 


I— ihw 


address 


address 

- all — 


*—iac_reg —i 


-bp — set 


- dacr —i— address 

- dacw 
_ dacrw . 

I— dvc — dvc_reg — data 


L dac_reg-i L size -I 


L enable — mode -I 


set —|- 1 - 


at fileiline — 

L ihw — 1 


— at line _ 

clear 


_ in “function”— 


bp — clear 


dacr 

dacw 

dacrw 


1 —dvc 


set 


I_clear _I 


range 


address 


dvc_reg — 1 


inc 


|_ inct —| 
exc - 
exct _ 


regl 


■ reg2 


5-20 


RISCWatch Debugger User's Guide 







bp 


Description 

The bp command is used to set or clear hardware and software breakpoints. 

Software instruction breakpoints are set using the ‘bp set address’ syntax. 
Hardware breakpoints are set by using the ‘bp set’ syntax with the desired 
pre-defined keyword (which uses the first available instruction/data breakpoint 
register to set an instruction/data breakpoint). The ‘bp clear address’ syntax 
applies to both hardware and software instruction breakpoints. 

Flags 

clear Clear one or all breakpoints 

set Set a breakpoint 

address Address of the data or instruction where the breakpoint should 

be set or cleared 

iac_reg 400Series: Instruction Address Compare Register Name (IAC1, 

IAC2, ...) 

all Remove all breakpoints(hardware and software) 

dacr 400Series: Break on Data Address Compare Read 

dacw 400Series: Break on Data Address Compare Write 

dacrw 400Series: Break on Data Address Compare Read or Write 

dac_reg 400Series: Data Address Compare Register Name (DAC1, 

DAC2) 

size 400Series: Data Address Compare Size bit settings (0,1,2, or 3) 

dvc 405Only: Break on Data Value Compare 

dvc_reg 405Only: Data Value Compare Register Name (DVC1, DVC2) 

enable 405Only: Data Value Compare byte enable. Indicates which data 

bytes are to be compared. (Any combination of 0, 1,2, and 3, or 
“ALL”) 

mode 405Only: Data Value Compare mode. Indicates how data bytes 

are to be compared. (AND, OR, AND-OR, or UNDEF to reset) 

ihw An optional parameter that is used to set a hardware instruction 

breakpoint using the first available instruction breakpoint register 
for the target processor. 

range 405Only: Break on Address Range 

exc 405Only: Address Range is exclusive 
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bp 


exct 405Only: Address Range is exclusive with toggle (toggle 

between exclusive and inclusive each time bp is hit). This option 
is only supported when regl and reg2 specify IAC registers. 

inc 405Only: Address Range is inclusive 

inct 405Only: Address Range is inclusive (toggle between inclusive 

and exclusive each time bp is hit). This option is only supported 
when regl and reg2 specify IAC registers. 

regl 405Only: Address Range lower bound register name. (IAC1, 

IAC3 for instruction range, DAC1 for data range) 

reg2 405Only: Address Range upper bound register name. (IAC2 if 

regl is IAC1, IAC4 if regl is IAC3. DAC2 for data range) 

at Indicates a source file line number is to follow. Used when the 

environment is set to ‘Source Mode On'. 

fileiline A source file name followed by a decimal number indicating a 

specific source line. 

line A decimal number indicating a specific source line in the 

currently active file (the file displayed in the Source window, or 
last file specified with the file command). 

in Indicates a function name is to follow. Used when the 

environment is set to ‘Source Mode On’. 

“function” A case sensitive function name, as it would appear in the 

Functions window. If the surrounding quotes are omitted, the 
function name must be a non-blank character string. If the 
specified function is not found in the currently active file, the 
search continues in all remaining files defined by the currently 
active program (program containing the current instruction 
address). 

When searching outside the currently active file, global functions 
take precedence over functions defined as static and the first 
static function is used if no global definition is found. 

The break point will be set/cleared at the first line of the function 
(if line table information exists) or at the function start address if 
no line table information exists. 


Notes 


Data Value Compare breakpoints can only be set if the corresponding Data 
Address Compare breakpoint has already been set. Similarly, Range breakpoints 
can only be set if the corresponding Address Compare breakpoints have both 
been set for the specified range registers 

For additional information on these and other processor debug features, consult 
the Debugging chapter of the User’s Manual for the specific PowerPC 400Series 


5-22 


RISCWatch Debugger User's Guide 




bp 


processor being used. Not all features shown above are supported across all 400 
Series processors. 


Examples 

• Set a software breakpoint at address OxFFFFFFO. 

bp set OxFFFFFFFO 

• Clear a breakpoint at address OxFFFFOOCO. 

bp clear OxFFFFOOCO 

• Clear all breakpoints. 

bp clear all 

• Set a hardware instruction breakpoint at address OxFFFFOODO using the first 
available instruction breakpoint register for the target processor. 

bp set ihw OxFFFFOODO 

• Set a hardware instruction breakpoint at address OxFFFFOCOO using the IAC2 
hardware register. 

bp set ihw OxFFFFOODO IAC2 

• Set a hardware instruction breakpoint at any address greater than or equal to 
0xFFFF8000 but less than OxFFFFFFOO. 


bp 

set 

ihw 

0xFFFF8000 

IAC1 

bp 

set 

ihw 

OxFFFFFFOO 

IAC2 

bp 

set 

range inc IAC1 

IAC2 


• Set a Data Address Compare breakpoint at address OxOOOOFFFO, using the 
DAC1 hardware register, and ignoring the LSB of the word address. 

bp set DACRW OxFFFO DAC1 1 

• Set a Data Value Compare breakpoint at 0x00000000, if the first halfword of 
the data location equals 0x12 when read. 

bp set DACR 0x00000000 DAC2 
bp set DVC DVC2 0x1234 01 AND 

• Set a Data Value Compare breakpoint at OxFFFFI 000, if the second or fourth 
byte of the word is written with 0xA5. 

bp set DACW OxFFFFlOOO DAC1 
bp set DVC DVC1 0x00A500A5 13 OR 
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Syntax 



Description 

bpmode is used to set or query the Breakpoint Mode used during debug. When 
the Breakpoint Mode is set to software (the default), operations to set breakpoints 
on the Source window, Assembly Debug window, and Functions window will result 
in a software breakpoint being set. When the Breakpoint Mode is set to hardware, 
operations to set breakpoints in these windows will result in a hardware 
breakpoint being set (if hardware facilities are available). 

Entering the bpmode command with no parameters will echo the current 
Breakpoint Mode setting. 

Note that the Breakpoint Mode can also be set via the Breakpoint Mode groupbox 
on the Breakpoints window. 

Flags 

hw | hardware Set the Breakpoint Mode to hardware. All user generated 
breakpoints will be applied using hardware breakpoint 
registers. Breakpoints used during line step and call step 
operations are applied using software trap instructions if the 
step option is not used. 

step Set the Breakpoint Mode to hardstep mode. All user specified 

breakpoints and internally generated breakpoints (those 
applied during line step and call step) will be applied using 
hardware breakpoint registers. 
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sw | software Set the Breakpoint Mode to software. 


See Also 


• “Assembly Debug Window” on page 3-54 

• “Breakpoints Window” on page 3-73 

• “Functions Window” on page 3-62 

• “Managing Breakpoints” on page 3-70 

• “Source Window” on page 3-51 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

callstep -►-* 

Description 

callstep steps into the called routine. 

callstep causes program control and debugger context to switch to the function 
call specified by the current source line. If the current line does not contain a 
function call, the command simply performs a line step. 

If the current line contains a function call with functions in the parameter list 
(fund (func2(),func3());), then a callstep will first enter the function(s) found in the 
parameter list. A subsequent return step would return to the original function call 
source line. When all of the parameter list functions have been entered and 
returned from using callstep/retstep commands, the next callstep will transfer 
the debugger context to the function contained in the original call. In the above 
example, to enter fund, the first callstep would enter func2(). A retstep would 
return to the source line containing the fund call. The next callstep/retstep 
would enter and then return from func3(). Finally, the next callstep would enter 
fund. 

Note: If a callstep is issued into a function that has no associated debug 
information, a retstep command should be issued to return immediately to the 
calling function. Alternatively, a breakpoint should be set on the source line 
immediately following the function call to assure that the return can be made. 

See Also 


• bp on page 3-20 

• retstep on page 3-112 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 


► — capture 



Description 

capture copies the contents of a user interface window and writes it to a file. The 
command options select which window's contents will be captured or all of the 
preceding choices (depending on the set of flags associated with a particular 
PowerPC processor). 

To capture the contents to a specific file, simply put the filename as the last option 
on the command line. If no filename is supplied, a default name of rwppc.cap will 
be used. To best understand how this command works simply type capture all on 
the command line and then view the file rwppc.cap. 

Source level debug windows (those included under the window parameter) will 
only be captured if the window is visible. The default for source level debug 
windows is to capture only the visible lines for a window. The total keyword can be 
used to capture the entire contents of any source level debug window except for 
the Source window. Only the visible lines will ever be captured for the Source 
window. 

Be advised that the information saved into captured files cannot be loaded back 
into the window from which it was captured or to the processor. To store and 
restore a particular processor state of memory and/or registers, use the save and 
load commands. 
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Flags 

Some flags listed below are only applicable to particular target processors, as 
indicated in the description of those flags. The set of windows selected by the all 
flag is also processor-dependent. 

all Specifies that the contents of all visible capturable windows are 

to be captured. 

filename Specifies the name of the file to which the window capture is 

written. 

total If this flag is specified, the entire contents of the window will be 

captured for those windows which support this flag (see table 
below). If this flag is NOT specified, only the visible contents will 
be captured. 

For some windows which display processor data, using this flag 
may require a read of target resources since the window may not 
contain all necessary data due to performance restrictions. 

Note: If the all option is specified, only the visible lines will ever 
be captured for the Source window. If the total option is used 
when specifying the Source window individually, the entire 
window will be captured without the status subwindow 
information. This option may be useful for capturing the contents 
of a file in mixed mode. When using the total option, care should 
be taken to ensure there is sufficient disk space to hold the 
desired screen information. 

Some windows contain multiple panes of data. If a specific pane 
is specified, only its data will be captured. If a pane is NOT 
specified for a window with multiple panes, all panes for that 
window will be captured. 

The supported pane keywords are listed under “Command 
Quick Reference” on page 5-4. 

When ASIC is specified for window, this specificies a unique 
ASIC window which contains the registers with the specified 
prefix. See the description for this flag in “Command Quick 
Reference” located at the beginning of this chapter. 

Any of the list of window keywords in “Window Quick Reference” 
on page 5-3. 

If a window has multiple instances and/or an associated MPS id, 
the appropriate instance number and/or MPS id must be 
specified as it appears in the window title bar. 


pane 


reg_pre 


window 
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Table 5-2. Windows that support capture and total 


capture 

supported 

total 

supported 

capture 

supported 

total 

supported 

capture 

supported 

total 

supported 

Cache 

Yes 

Register Field 

No 

Locals 

Yes 

Memory Access 

Yes 

Breakpoints 

Yes 

OS Open 

Yes 

Memory ASCII 

No 

Callers 

Yes 

Programs 

Yes 

Memory Custom 

No 

Files 

Yes 

Source 

Yes 

Debug 

No 

Functions 

Yes 

TLB 

Yes 

Output 

Yes 

Globals 

Yes 

User-Defined 

No 

Register 

No 

Inspect 

Yes 
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Description 

cfss is used to set and clear stop points in the Command File Window. A stop 
point is used to halt command file execution at a specific line number. Stop points 
remain active for the entire RISCWatch debug session and can only be removed 
using the ‘cfss clear’ command. 

Flags 

sp Specifies that a stop point command is being issued, 

set Specifies that a stop point is to be set. 

clear Specifies that a stop point is to be removed, 

all Specifies that all stop points are to be removed. 

at fileiline Specifies the file name and line number for the stop point. If the 

file name cannot be located using the RISCWatch search path, 
an error message is generated. 

at line Specifies the line number for the stop point. The command file 

name is assumed to be the currently active file shown in the 
Command File Window. 

Examples 

• Set a stop point at line 5 of command file ‘startup.cmd’. 

cfss sp set startup.cmd:5 

• Remove the stop point located at line 5 of the file shown in the Command 
window. 
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See Also 


cfss sp clear 5 


See "Command File Window" on page 3-135 
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Note: Command not valid when in MPS mode. 


Syntax 

» -color 


Description 

color is used to change window color settings. The settings specified by this 
command are applied to any subsequent window creations. 

The color command can be used to override the default settings, as well as any 
settings previously defined in the environment file. If no keyword is specified, the 
current settings will be displayed. 

Flags 

reset Specifies that the color settings are to be reset to the original 

session values. 

cback Specifies the color setting for the background control areas, 

cfore Specifies the color setting for the foreground control areas, 

tback Specifies the color setting for the background text areas, 

tfore Specifies the color setting for the foreground text areas. 
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wback Specifies the color setting for the background window areas, 

wfore Specifies the color setting for the foreground window areas. 

color Name or hex representation of the desired color. Named colors 

available are black, blue, cyan, dkgray, gray, green, Itgreen, 
magenta, read, white, and yellow. The hex representation of 
“Oxrrggbb” defines the red, green, and blue component of the 
color, respectively. 


Examples 

• Change the window background color to blue. 

color wback blue 

• Change the control foreground color to blue using the hex representation. 

color cfore OxFF 

See Also 

• See "Environment Resources" on page 3-5 

• See "Multi-Processor Resources" on page 3-28 
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401 /5x 

403x 

602 

603x 

604x 

7xx 

JTAG 



• 

• 


• 

OS Open 


ROM Mon 



Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Notes: Only JTAG Ethernet targets are supported. 

32bitmode options are for 602, 603, 603e, 603ev and 740/750 processors 
only. 

Drtry option is for 603 processor only. 

Parity flags are for 603, 603e, 603ev and 740/750 processors only. 

TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


config 


■ drtry- 

parity _ 

.32bitmode 


. on 
off 


Description 

config configures RISCWatch to match different hardware options for a particular 
processor. Selecting an option without a value setting will display the current 
setting. 

Note: RISCWatch cannot automatically detect the processor’s settings, nor can it 
change the mode of the processor itself. 


Flags 

drtry Used to display or change RISCWatch’s drtry setting. For 603 

processors which are run in Data Retry (DRTRY) mode, drtry 
must be set to yes for RISCWatch to operate properly. 

parity Used to display or change RISCWatch’s data parity generation 

setting. For performance reasons, RISCWatch does not typically 
generate data parity bits on memory accesses. However, some 
systems may require parity generation. 

32bitmode Used to display or set RISCWatch’s 32bitmode setting. This 
setting must match the 32bitmode setting of the processor’s 
hardware for correct RISCWatch operation. 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

create is used to create a variable. The variable value is stored as a signed 
quantity allocated in multiples of 4 bytes), a float, or an expression. The name 
given to the variable may not start with a number and must not match any 
processor register name. Variable names are also case sensitive. 

The variable can be used in any command that allows int_var, flt_var, orstr_val as 
valid input parameters. See Table 5-1 for a command syntax summary that shows 
which commands accept create variables as parameters. 

It is possible to assign an initial value to the variable. If no initial value is specified 
when creating a variable, a value of 0 will be assigned. 

Flags 

“expression” An expression, enclosed in double quotes, that is placed into the 
created variable. This creates a string variable. 

variable Name of the immediate variable to be created. 

initial_value The value assigned to the variable after it is created. If an initial 
value is not specified, a value of 0 will be assigned. 

Examples 

• Create a variable named cr_var1 and assign it an initial value of 0x1234. 

create cr_varl = 0x1234 
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See Also 


• Create a variable named cr_var2 and assign it an initial value of 0. 

create cr_var2 

• Create a variable named my_string and assign it the string “My string contents”. 

create my_string = "My string contents" 

• Create two variables, i and j, and use them to calculate a value to write to 
GPRO. 


create i 
create j 

set i = (0x12345678) 
set j = i - IAR 
write R0 j 


# create variable i 

# create variable j 

# read memory into i 

# subtract IAR from i 

# write value of j to GPR 0 


• assign on page 3-13 

• set on page 3-117 
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Description 

delay is used to delay the execution of a command file for the specified number of 
seconds. During this delay period, no program or command file processing is 
performed. 

Flags 

value Specifies the number of seconds to delay execution 

int_var Any int variable created with the create command 

imm_var Any immediate variable created with the assign command 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 


OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 

Syntax 

— detach -► -» 

Description 

detach ends a source mode debug session by disconnecting from the thread or 
process being debugged. The thread or process then continues to run normally. 

Examples 

• Detach from the thread or process being debugged. 

detach 

See Also 

• attach on page 3-17 

• kill thread on page 3-70 

• start thread on page 3-129 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

dis is used to disassemble a 4-byte instruction value. The result, by default, is 
printed as a mnemonic and its operands in assembly code but can also be stored 
into a string variable. The options for this command allow disassembly of an 
immediate value or the contents of a specified processor memory location, 
register or user-variable. 


Flags 


value 

(address) 


int_var 

reg_name 

reg_var 

str_var 


Specifies an immediate numeric value. 

Specifies a memory location which will be read and its contents 
then disassembled. Note that the () characters are used to 
distinguish a memory address from an immediate value. 

Any int variable created with the create command. 

Specifies any valid register name whose value will be 
disassembled. 

Any register variable created with the assign command. 

Any string variable created with the assign or create 
commands. 
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Examples 

• Disassemble an immediate value. 

dis 0x38000000 

• Disassemble the instruction that resides at a given memory address. 

dis (0xlD3F0004) 

• Disassemble the value contained in a user-created variable. 

create dis_val = 0x38000000 
dis dis_val 

• Disassemble the value contained in a register and store the result in a 
user-created string variable. 

write R14 0x38000000 
create my_str = "" 
dis R14 my_str 

See Also 

• assm on page 3-15 
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Syntax 



Description 

down scrolls the contents of a window down one or more lines from the top line 
visible in the window. 

The lines variable initially defaults to 1. If the value specified for lines is larger than 
the number of lines left in the window, the last line is shown at the bottom of the 
window. 

If the window keyword is not specified, the last window specified for this command 
is used. It initially defaults to the Source window. 

If neither the lines variable nor the window keyword is specified, the last lines 
value and window keyword specified for the command are used. 

Flags 

lines Specifies the number of lines to be scrolled down. 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 
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Examples 

• Scroll down one line in a window previously specified, or the Source window if 
none has been specified previously. 

down 

• Scroll down 10 lines in a window previously specified, or the Source window if 
none has been specified previously. 

down 10 

• Scroll down 12 lines in the global variables window. 

down 12 globals 

See Also 

• up on page 3-141 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 


Cmd Line Cmd File 

TTY 

• 



Syntax 


end 



Description 

end is used to end the execution of the current command file, end all is used to 
end the execution of all command files, regardless of nesting. 

Examples 

• End execution of the current command file. 

if (RO != 0xFC001234) 
end 
endif 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


.exec 


-command file ■ 


-{variablejist }. 


-step 


Description 

exec is used to execute the instructions contained in a command file. See the 
Command Files section for more details on command file creation and usage. 


Flags 


command_file 


variablejist 


step 


The name of the command file to be executed. For example, 
test.cmd. For further information, see “Command File 
Programming” on page 3-127. 

A list of variable values to be passed into the command file and 
assigned to the variables in the parms parameter definition. See 
“Command File Parameters” on page 3-130 for more details. 

Runs the command file in single-step mode. This option is only 
valid when a command file is executed from the user interface. It 
causes a Command File window to be created, which is 
equivalent to issuing the “window cfss command_file” command. 
See “Command File Window” on page 3-135 for more details. 


See Also 


• window on page 3-148 


5-44 


RISCWatch Debugger User's Guide 




expr 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


expr 


_ expression 




Description 

expr is used to evaluate an expression and print the results in a status message. 
For a complete description of the expression syntax see the set command. 

The expr command outputs the result of the expression in hexadecimal, signed 
decimal and unsigned decimal forms. Having such a capability allows users to test 
out expressions before they are used on the command line or in a command file. It 
also allows numbers to be displayed in multiple radices (hexadecimal, decimal, 
and unsigned decimal). To display a number in its alternate base, simply type it in 
after the expr command keyword. 

Flags 

expression 
logical 

mathematical 
expression 
func 
log_op 
math_op 1 
math_op2 
# 

Examples 

• Display the result of adding 10 to GPRO. 

expr R0 + 10 


= [(] logical|mathematical [)] 

= expression|expression log_op expression 
= [math_op1] expression [math_op2 mathematical] 

= reg_name[.fld_name|.#]|(address)|immed|variable|mem_var|func 
= supported functions : random]) 

= ==!=>>=< <= 

= + - ~ 

= + - * / mod % & | A « » 

= ordinal bit number 
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• Display the value 10 in hexadecimal, decimal, and unsigned decimal. 

expr 10 

See Also 

• set on page 3-117 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


fctrl 


— append 

— new — 

— close 

— errors 

— log 

— status 


■ filename 
filename 


r° ff — 

_on 


Description 

fctrl controls access of the print files used by the fprint command. 

Flags 


append 

Open a print file. If the file exists, it will be opened and all 
messages will be appended to the end of the file. 

new 

Open a print file. If the file exists, it will be erased. 

close 

Close the print file. 

errors 

This flag controls whether or not program error messages are 
copied to the print file. 

log 

This flag controls whether or not log messages are copied to the 
print file. 

status 

This flag controls whether or not program status messages are 
copied to the print file. 
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off Disables message copying, 

on Enables message copying. 

filename The name of the print file to open. 

Examples 

• Open a new file for printing. 

fctrl new print.dat 

• Enable copying of error messages to the print file. 

fctrl errors on 

• Close an open print file. 

fctrl close 

See Also 

• fprint on page 3-59 

• print on page 3-105 


5-48 


RISCWatch Debugger User's Guide 




file 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

file sets the current source file to filename (if specified) and displays it in the 
Source window if the Source window is active. Entering file without specifying a 
filename displays the name of the current file, if available. 

file can be used in conjunction with the ‘at’ and ‘in’ options of the bp command to 
set the current file used by those options. 

Only files which belong to the program currently being debugged, and which were 
compiled to contain debug information, can be displayed using this command. 
The valid file names are those which are shown in the Files window. 

Flags 

filename Specifies the name of the source file to make current and display 

in the Source window. 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 


find 


— string - 


string 


'— SlastS-1 


window 




pane 


Description 

find searches for a string in a window, scrolling to the line containing the string, 
and highlighting the string if found. 

The search is case-insensitive ('non-exact'). If no text is currently highlighted, the 
search will begin from the beginning of the top line visible in the window. If there is 
text highlighted, the search will begin from either the first character of the selected 
text (an 'initial' search), or from the character immediately following the first 
character of the highlighted text (a 'next' search). The focus command can be 
used to locate highlighted text. 

If no parameters are specified, the string last specified for a find command (find, 
findb, finde) is used, and a ‘next’ search is done. This allows the user to initially 
specify a string, and find subsequent occurrences of the string in the same 
window by simply entering a find command repeatedly. A ‘next’ search will also 
be done if the string and window values match those of the last attempted find 
command. This allows the user to initially specify a string, and find subsequent 
occurrences of the string in the window by double-clicking on the command in the 
command history list of the Main window. 

If the string variable is specified, and the string and window values do not match 
those of the last attempted find, an ‘initial’ search is done. If the window keyword 
is not specified, the last window specified for this command is used. It initially 
defaults to the Source window. 

If the keyword $last$ is specified in place of string and a window is specified, the 
string specified for the last find command is used, and a ‘next’ search is done for 
the specified window. This allows a window different from the window specified in 
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the previous search to be searched for the same string specified in the previous 
search. 

This function is also available via the input line, as described in “Input Line Usage” 
on page 3-48. 


Flags 

string Sequence of characters to be found. 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 


See Also 


• findb on page 3-52 

• finde on page 3-54 

• focus on page 3-56 
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Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 
— findb ■ 


- string - 

|— string -,- window ■ 


$last$ 






pane — 1 


Description 

findb searches backwards for a string in a window, scrolling to the line containing 
the string, and highlighting the string if found. 

The search is case-insensitive (‘non-exact’) or case-sensitive (‘exact’), depending 
on the type of forward search (find orfinde) which was done previously. If no 
forward search was done previously the command defaults to a ‘non-exact’ 
search. 

If no text is currently highlighted, the search will begin from the end of the bottom 
line visible in the window. If there is text highlighted, the search will begin from 
either the last character of the selected text (an ‘initial’ search), or from the 
character immediately preceding the last character of the highlighted text (a ‘next’ 
search). The focus command can be used to locate highlighted text. 

If no parameters are specified, the string last specified for a ‘find’ command (find, 
findb, finde) is used, and a ‘next’ search is done. This allows the user to initially 
specify a string, and find subsequent occurrences of the string in the file by simply 
entering a ‘find’ command repeatedly. A ‘next’ search will also be done if the string 
and window values match those of the last attempted ‘find’ command. This allows 
the user to initially specify a string, and find subsequent occurrences of the string 
in the window by double-clicking on the command in the command history list of 
the Main window. 

If the string variable is specified, and the string and window values do not match 
those of the last attempted ‘find’ command, an ‘initial’ search is done. If the 
window keyword is not specified, the window specified for the last ‘find’ command 
is used. It initially defaults to the Source window. 
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If the keyword $last$ is specified in place of string and a window is specified, the 
string specified for the last find command is used, and a ‘next’ search is done for 
the specified window. This allows a window different from the window specified in 
the previous search to be searched for the same string specified in the previous 
search. 

This function is also available via the input line, as described in “Input Line Usage” 
on page 3-48. 

Flags 

string Sequence of characters to be found. 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 

See Also 

• find on page 3-50 

• finde on page 3-54 

• focus on page 3-56 
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Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 


finde 


- string — 

|— string -,- window 


I— $last$ —I 


I —pane — 


Description 

finde searches for a string in a window, scrolling to the line containing the string, 
and highlighting the string if found. 

Unlike the find command, finde does an case-sensitive ('exact') search. If no text 
is currently highlighted, the search will begin from the beginning of the top line 
visible in the window. If there is text highlighted, the search will begin from either 
the first character of the selected text (an 'initial' search), or from the character 
immediately following the first character of the highlighted text (a 'next' search). 
The focus command can be used to locate highlighted text. 

If no parameters are specified, the string last specified for a finde command (find, 
findb, finde) is used, and a ‘next’ search is done. This allows the user to initially 
specify a string, and find subsequent occurrences of the string in the same 
window by simply entering a finde command repeatedly. A ‘next’ search will also 
be done if the string and window values match those of the last attempted finde 
command. This allows the user to initially specify a string, and find subsequent 
occurrences of the string in the window by double-clicking on the command in the 
command history list of the Main window. 

If the string variable is specified, and the string and window values do not match 
those of the last attempted finde, an ‘initial’ search is done. If the window keyword 
is not specified, the last window specified for this command is used. It initially 
defaults to the Source window. 

If the keyword $last$ is specified in place of string and a window is specified, the 
string specified for the last finde command is used, and a ‘next’ search is done for 
the specified window. This allows a window different from the window specified in 
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the previous search to be searched for the same string specified in the previous 

search. 

This function is also available via the input line, as described in “Input Line Usage” 

on page 3-48. 

Flags 

string Sequence of characters to be found. 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 

See Also 

• find on page 3-50 

• findb on page 3-52 

• focus on page 3-56 
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Syntax 



Description 

focus scrolls to the line of a window which has text highlighted, if any. 

If no text is currently highlighted in the window, a message is generated stating 
this fact. If the window keyword is not specified, the last window specified for this 
command is used. It initially defaults to the Source window. 

Flags 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 
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Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

-►-*_fold 


on 


— off — 1 


Description 

fold controls instruction folding. Refer to the applicable PowerPC processor 
documentation for detailed information on instruction folding. 

A fold setting is effective only until the next processor system reset. After a reset, 
the fold setting defaults to ‘on’. 

If no parameter is entered, the current fold setting is displayed. 

Flags 

off Turns instruction folding off. 

on Turns instruction folding on. 
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Modes 

Cmd Line Cmd File 

TTY 

• • 


Syntax 


.fprdisp. 


|— hex —| 
-sci - 


Description 

fprdisp controls the display mode of the Floating Point Register window. The 
default is to display the values on the screen in hexadecimal notation. 

If no parameter is entered, the display setting is toggled. 

Flags 

hex Display FPR window values in hexadecimal notation, 

sci Display FPR window values in scientific notation. 
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Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

-—fprint — print_string -». ^ 

Description 

fprint prints user definable strings to a print file that was opened with the fctrl 
command. 

String literals are ASCII text enclosed by quotation (") marks. The text between 
the quotation marks is echoed to the print file. A string literal is also used to 
enclose character constants to help format the printed text: 

Constant Meaning 

\b Backspace 

\f Form feed 

\n Newline 

\r Carriage return 

\t Tab 

User-created variable values may also be printed to the print file if they appear in 
the print string. Expressions containing variables and constants may also be 
used. 

Variable values printed to the print file can be written in a variety of forms. 
Available options include the ability to print integers as signed or unsigned, 
hexadecimal values and characters. 

The syntax for using variable formatting is as follows : 

variable!/[+] [[0]#] c|i|u|x|E|X] 

where 

/ Terminates the string to be formatted 
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+ Prints an integer preceded by a + or - sign. This option is only 

valid for the i format. 

# Specifies that at least # characters are printed. If the result 

contains less than # characters, the output will be left-padded 
with spaces. This option is only valid for the i, u, x, and X 
formats. 

0 This option, if included, must always precede the # option. This 

specifies that at least # characters are printed. If the result 
contains less than # characters, the output will be left-padded 
with Os. This option is only valid for the i, u, x, and X formats. 

c Prints a value as a series of four ASCII characters. Unprintable 

characters are output as a period (.). 

i Prints a value as a signed integer. 

u Prints a value as an unsigned integer. 

x Prints a value as a hexadecimal integer. The letters a, b, c, d, e, 

and f appear in the output. 

X Prints a value as a hexadecimal integer. The letters A, B, C, D, E, 

and F appear in the output. 

E Prints a value in scientific notation (i.e. n.nnE-n). 

X Prints a value as a hexadecimal integer. The letters A, B, C, D, E, 

and F appear in the output. 

To use variable formatting, place the / character immediately after the last 
character of the variable name and then follow it with the formatting options you 
desire. To format expressions, place the formatting options directly after the last 
argument in the expression. For example: 

fprint addr + 0x1234 / 4/08X 

A single fprint statement may contain multiple string literals, variables and 
expressions in any order. If this is done, each item in the command must be 
separated with a comma (,). 

The following pseudo-variables may be used in the print and fprint commands for 
your convenience : 

$DATE This will be replaced by a string which contains the current date 
in the format DAY MONTH DATE YEAR. 

$ERRORS This will be replaced by a string which contains the number of 
errors generated by executed commands. 

$TIME This will be replaced by a string which contains the current time 
in the format HOUR:MINUTE:SECOND. 


5-60 


RISCWatch Debugger User's Guide 




fprint 


$TIMER This will be replaced by a string which contains the number of 
seconds in the clock timer. See the timer command for more 
details. 

Flags 

print_string This is a user definable string containing string literals, 

user-created variable names and the same type of expressions 
used in the set command. 

Examples 

The following commands implement a short loop which writes successive memory 
locations, reads back what was written and prints the result of the comparison 
between the two values : 

fctrl new test.mem 
fprint "Start : ", $TIME, "\n" 
create mem_addr = OxOOOOFFFF 
while (mem_addr < 0x00010000) 

fprint "Addr : ", mem_addr/08X 
fprint "\n" 

write dmem mem_addr 0xFFA55AFF 
read mem_addr SO 
if (SO == 0xFFA55AFF) 

fprint "Test : PASSED\n\n" 
elseif 

fprint "Test : FAILED\n\n" 
endif 

set mem_addr = mem_addr + 1 
endwhile 

fprint "End : ", $TIME, "\n" 
fctrl close 

See Also 

• fctrl on page 3-47 

• print on page 3-105 
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Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


-freeze 


—always — 
-never- 


stop 


Description 

freeze controls how and when the processor timers are to be frozen. 

A freeze setting is effective only until the next processor reset. After any reset, the 
freeze setting defaults to ‘never’. 

If no parameter is entered, the current freeze setting is displayed. 


Flags 

always Forces timers to be frozen regardless of the processor state. 

never Forces timers to be free running (not frozen) at all times 

regardless of the processor state. 

stop Forces timers to be frozen whenever the processor is stopped. 

Timers will remain stopped until the next run is performed. 
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Modes 

Cmd Line Cmd File 

TTY 

• • 


Syntax 


. funcdisp 


— all_addr- 

— allname- 

—dbg_addr— 

— dbgname — 


Description 

funcdisp changes the Functions window display to show either all functions in the 
program sorted by address (all_addr), all functions in the program sorted by 
name (all_name), functions with symbolic debug information sorted by address 
(dbg_addr), or functions with symbolic debug information sorted by name 
(dbg_name). This is the same capability provided by the Functions Mode 
groupbox on the Functions window. 

Entering the funcdisp command with no parameters will toggle the current 
Functions window display (from functions with symbolic debug information to all 
functions, or the reverse), while keeping the sort algorithm for the display (by 
name or by address) the same as the current display. 


Flags 


all_addr 

all_name 

dbg_addr 

dbg_name 


Sets the Functions window display to show all functions in the 
program, sorted by addr. 

Sets the Functions window display to show all functions in the 
program, sorted by name. 

Sets the Functions window display to show only functions with 
symbolic debug information, sorted by addr. 

Sets the Functions window display to show only functions with 
symbolic debug information, sorted by name. 
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Example 


See Also 


• Set the Functions window display to show all functions in the program, sorted 
by address 

funcdisp all_addr 


“Functions Window” on page 3-62 
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TTY 

• • 



Syntax 

»• »— goto 


line --r 

/abe/ - 

addr - address — 

line - filedine — 




Description 

goto causes the source line designated by line to be the next source line run. The 
specified source line must be in the same function as the current source line. 


Flags 

label 

line 

addr 

line 

address 

filedine 


Specifies the location within a command file to transfer execution 
control. 

Specifies the next source line to be run in the file which contains 
the current instruction. 

Specifies execution is to be resumed at a given address. 

Specifies that execution is to be resumed at a given 
filename:line_number. 

Address at which to resume execution. 

File name and line number at which to resume execution. 


Example 

• Change the next source line to be executed to line 100 of the current file. 

goto 100 

• Change the next source line to be executed to line 10 of a file. 

goto line hello.c:100 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


halt 


— off — 

— on — 


Description 

halt controls the state of the processor Halt line. If neither the on nor the off 
parameter is specified, it displays the current Halt line state. 


Flags 

on Activate the Halt line, 

off Deactivate the Halt line. 
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Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 


-hidewins 


Description 

hidewins hides all the currently visible RISCWatch windows except for the Main 
window. 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

- ip -ft* ~*- 

Description 

ip generates messages in the I/O window giving the current Instruction Pointer 
address, as well as the Function, File, Line Number, and Current Program 
associated with the ip address if there is debug information available 
corresponding to it. 

For JTAG targets, the Instruction Pointer is actually the current Instruction Address 
Register (IAR). For non-JTAG targets, it is the process copy of the IAR for the 
application being debugged. 

See Also 


• showip on page 3-123 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 

Syntax 


jtag -clock 


I_ value _I 


Description 

jtag displays or sets the JTAG TCK clock speed on the RISCWatch Processor 
Probe. 


Flags 

value Specifies the clock speed to set, where: 

1 = 10MHz 

2 = 5MHz 

3 = 2.5MHz 

4 = 1.25MHz 

5 = 625KHz 

6 = 312.5KHZ 

7 = 156.25KHZ 

for the older probes. 

For the newer probes, values 1 to 7 are still supported but 
the actual value of the JTAG clock will be different 
based on the processor. The values that should be 
used are 512K, 1M, 2M, 3M ... 40M. For example, 

“jtag clock 20M” will set the jtag clock to 20MHz. 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

— killthread- 

Description 

kill_thread ends a source mode debug session with OS Open by destroying the 
thread which is currently being debugged. 

Examples 

• Kill the current thread 

kill_thread 

See Also 


• attach on page 3-17 

• detach on page 3-38 

• start thread on page 3-129 
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Cmd Line Cmd File 
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Syntax 


line 


— line 


I— line — window ■ 


'■—pane — 1 


Description 

line scrolls the contents of a window to a physical line of text in the window. 

If the line number specified is larger than the number of lines in the window, the 
last line is shown at the bottom of the window. If the window keyword is not 
specified, the last window specified for this command is used. It initially defaults to 
the Source window. If neither the line number nor the window keyword is 
specified, the last line number and window specified for the command are used. 
The line number initially defaults to 1. 

This function is also available via the input line, as described in “Input Line Usage” 
on page 3-48. 

Flags 

line 

window 


pane 


Specifies the physical line number to be scrolled to. 

The window keyword applies to a subset of the windows listed in 
“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

See list of pane keywords in “Command Quick Reference” on 
page 5-4 (page 5-3). 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

— linestep 


value 


Description 

linestep steps the program to the next source line. If a value is specified, the 
action is repeated for the number of times specified in the passed value. 

If the current source line contains a call to a function, that function and any 
subsequent functions will be executed until the program returns to the source line 
immediately following the current line, or until a breakpoint is hit. 

See Also 


• asmstep on page 3-12 

• callstep on page 3-26 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


load- 


I 


binary 
bin — 


-v 

— i 


dmem 


imem 


■ filename 


address 
int var _ 


imm var 


layout - 

— image- 

-motorola — 

— mot - 

-reg - 


filename 


- file 
_host 


j —filename — 

_d =addr_ 

_ s =addr_ 

_i=addr _ 

-tg=_ 

L exclude J 



_ss =size_ 





Description 

load is used to load memory, registers or window layout information using the 
contents of the specified file. Each of the load commands expect files formatted 
appropriate to the type of data they contain. 


Flags 

binary Load the contents of a binary file into data memory, 

bin Same as the binary flag. 

dmem This command is the complement to the save mem command 

and can only process those files which were generated by the 
save mem command. The file contains a block of memory 
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load 


imem 

layout 

file 

host 

image 


motorola 

mot 

reg 


address 

d= 


values in a human-readable ASCII format. This allows the saved 
state of the memory to be loaded back in at any time. 

When loading the saved memory block, the data can loaded to 
the same address from which it was saved, or a new address 
can be specified with the command allowing the data to be 
placed anywhere in the processor's memory. 

This command is the same as the load dmem command except 
that it ensures that the contents of the instruction cache is 
updated along with data memory. 

This command is used to load a window layout definition that 
was filed with a save command. 

Loads selective sections (text, data, etc.) of an ELF or XCOFF 
file into target memory and loads the host system with internal 
data structures used to perform source level debug. 

Loads the host system with internal data structures used to 
perform source level debug on ELF or XCOFF file formats. The 
target system is not altered. This command is used to enable 
source level debug on user applications which have been 
preloaded on the target system. ROM resident code is one 
example of a preloaded application. 

Loads the target system with the contents of a Boot Image file 
(images created with the eimgbld/nimgbld tool of the evaluation 
board support package). The first 32 bytes of data is assumed to 
be a ‘header’ record containing a ‘load address’ (bytes 4-7) and 
an ‘entry point address’ (bytes 16-19). All data following the 32 
byte header is loaded on the target system, starting at the ‘load 
address’. The instruction address register (IAR) is loaded with 
the value designated by the ‘entry point address’. See Loading 
Boot and Boot Image Files on page 3-46 for further 
discussions on the use of this flag. 

Load the contents of a Motorola format file into data memory. 
Same as the motorola flag. 

This command is the complement to the save reg command and 
can only process those files which were generated by the save 
reg command. The file contains all the processor register values 
in a human-readable ASCII format. This allows the saved state 
of the registers to be loaded back in at any time. 

Memory address to load file contents. 

Indicates that the specified address is to be used to locate the 
data segment (ELF and XCOFF formats only). 
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s= 

Indicates that the specified address is to be used to set the stack 
address (ELF and XCOFF formats only). If this value is not 
supplied, the STACK ADDR in the environment resources file 
will be used. THE USE OF THIS FLAG IS NOT 
RECOMMENDED. 

t= 

Indicates that the specified address is to be used to locate the 
text segment (ELF and XCOFF formats only). 

ss= 

Indicates that the specified size is to be used to calculate the 
stack address. The stack address is set to ‘size’ bytes beyond 
the last byte loaded on the target (usually the last byte of bss 
data). If this value is not specified, the STACK_SIZE in the 
environment resources file will be used. If STACK_SIZE is 
undefined, the default size of 16K bytes is used. 

exclude 

Portions of the load can be excluded to improve performance 
under certain circumstances. The options listed below can be 
used individually or together: 

nosym 

Indicates that symbol table and string table are NOT to be 
loaded on the target. This applies to boot files only (images 
created with 403GA evaluation board support package 
entry code). See “Loading Boot and Boot Image Files” on 
page 3-46 for a discussion of boot files. 

nozero 

This keyword directs RISCWatch to bypass segment 
initialization. Segment initialization is the term used to 
describe the act of zeroing out the uninitialized global 
variables (BSS) of an application. The ‘NOZERO’ keyword 
should only be used on applications which zero out their 
own initialization segments at program start up. 

size 

ss= byte count for stack size. 

tg= 

Specifies the thread group for OS Open systems with virtual 
memory support. See start_thread on page 3-129 for more 
information. 

filename 

Name of the file containing the data, in the appropriate format, to 
be loaded. 

int_var 

Any integer variable created with the create command. 

imm_var 

An assigned user-created variable specifying an immediate 
value that may be used as a data memory address. 


Note: If the file name specified in the load command is qualified (a directory path 
is indicated), then the file is search in the designated directory only. If the file 
name is not qualified, then the directory search will be governed by the order 
specified via the srchpath command; if not found, the current directory will be 
checked. 
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See Also 


• save on page 3-115 

• srchpath on page 3-126 

• start thread on page 3-129 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


log 


- message 




Description 

log writes typed message strings to the log file. The entire log message will be 
echoed to the log file just as if it had been typed on the command line. 

Messages will only be written to the log file if the logging command has been set 
to on (the default). 

Flags 

message The message to be written to the log file. 

Examples 

• Write the message 'R3 Test Passed' to the log file. 

if (r3 != 0x12345678) 
log R3 Test Passed 
endif 

See Also 

• logging on page 3-78 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


logging 


— off — 

— on — 


Description 

logging determines the current logging status and enables or disables the writing 
of log messages to the log file. On initial program start up, logging is set to on. 
This allows all commands and program error and status messages to be written to 
the log file for that session. 

To stop these messages from being written to the log file, use the off flag. No 
messages will be written to the log file until a logging on command is given. If 
neither the off nor on flag is specified, the command prints the current logging 
state. 

There is also an environment variable that is used to control logging while running 
a command file. This variable, CMD_FILE_LOG, is in the environment resources 
file (rwppc.env) and can be set to YES or NO. Use of this variable in no way 
affects the current setting of the logging state as set by the logging command. 
When running command files that are very large or contain loops that will execute 
many times, use of this variable is suggested to disable logging during the 
command file run. This will prevent a very large log file from being generated in 
such cases. 

Under normal circumstances, logging will be enabled. But should a case arise 
where a command file is generating log files that are too large, the 
CMD_FILE_LOG variable can be set to NO. This will keep the commands and 
messages generated by the command file out of the log file, allowing only 
commands entered from the command line and their messages to be logged. 
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Flags 

on Logging is turned on (enabled), 

off Logging is turned off (disabled). 

See Also 

• log on page 3-77 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

— logoff 




Description 

logoff allows a user to start an OS Open Boot Image using the ROM Monitor 
target. When issued, this command informs the ROM Monitor to leave the debug 
state and continue execution with any previously attached process. 

The sole purpose for logoff is to load and execute a Boot Image file. No debug is 
possible once this command is executed. See “Loading Boot and Boot Image 
Files” on page 3-46 for further details. 

Example 

• Load and execute an OS Open boot image file. 

load image applprog.img 
logoff 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 

Syntax 



Description 

memacc enables the user to define to RISCWatch unique address access 
restrictions for specified regions of memory. 


Flags 

clear Specifies that all user defined memory access entries are to be 

removed. Address validation proceeds using the default 
checking provided internally by RISCWatch. 

disable Specifies that RISCWatch is to ignore all user defined entries for 

address validation. Performs the same function as the clear 
option except the entries are not removed. 
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enable 

add 

delete 

use 

beg_addr 

end_addr 

access 


size 


type 


phy_addr 

logical 


Specifies that RISCWatch is to enable user defined access 
checking previously disabled by a memacc disable command. 

Specifies a new user defined address access entry is to be 
added. This entry will override any previously defined entry or 
internal default RISCWatch checking within the specified 
address range. 

Specifies that an access check entry is to be deleted. If the 
memacc add command was used to define two identical access 
entries, the last one added will be removed. 

Specifies a new RISCWatch Memory Access Mode. 

Specifies the beginning address for a region of memory. It can 
be in the form of an integer, imm_var : int_var, or mem_var. 

Specifies the end address for a region of memory. It can be in 
the form of an integer, imm_var : int_var, or mem_var. 

Specifies the allowable accesses for a region of memory. Valid 
types are the keywords NA (no access), RO (read only), WO 
(write only), or RW (read/write). Alternatively, a corresponding 
integer value can be specified explicitly, or in the form of an 
imm_var or int_var. Valid integers are 0 (NA), 1 (RO), 2 (WO), or 
3 (RW). The default if no access is specified is RW. 

Specifies the byte size of memory accesses within the region of 
memory. It can be in the form of an integer, imm_var, int_var, or 
mem_var. Valid values are 0,1,2, 4, or 8 bytes. If no size is 
specified, or a size of zero is indicated, it will be set to the default 
size as determined by the target processor (4 bytes for 4xx 
processors, 8 bytes for all other processors). 

Specifies the type of access to be checked for a region of 
memory. Valid types are the keywords IMEM (instruction only), 
DMEM (data only), or MEM (instruction and data). Alternatively, 
a corresponding integer value can be specified explicitly, or in 
the form of an imm_var or int_var. Valid integers are 1 DMEM, 2 
IMEM or 3 MEM. The default if no type is specified is MEM. 
Since users are not aware of how RISCWatch internally 
accesses memory, the default value of MEM should be used. 

Specifies a physical address associated with beg_addr. It can be 
in the form of an integer, imm_var, int_var, or mem_var. If not 
specified, phy_addr will be set to beg_addr. 

Specifies RISCWatch Logical Memory Access Mode. Addresses 
presented to RISCWatch will also map directly to some physical 
address (no address redirection will take place). The phy_addr 
field will be ignored. This is the default mode of operation for all 
RISCWatch memory reads or writes. 
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physical Specifies RISCWatch Physical Memory Access Mode. 

Addresses presented to RISCWatch will map to the physical 
addresses designated by the phy_addr field. This provides a 
level of user defined address translation. This address 
redirection will occur regardless of address translation state of 
the target processor. 


Examples 

• Disable all internal memory access checking done by RISCWatch by creating a 
user defined entry which defines the entire address space. 

memacc add 0x00000000 OxFFFFFFFF RW 

• Make the region of memory from 0 to OxFFFF read only with an access size of 
4. 

memacc add 0 OxFFFF RO 4 MEM 

• Make memory address 0x4000 write only with an access size of 1 byte. 

create serial_addr = 0x4000 
assign serial_size = 1 

memacc add serial_addr serial_addr WO serial_size 

See Also 

• “Core + ASIC Resources” on page 3-9 

• “Reading and Writing Memory” on page 3-104 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

memchk tests the integrity of the processor's memory. The values 0x00, 0xA5, 

OxFF and 0x5A are written to the specified address one at a time and then read 

back to verify that they were indeed written correctly. An error message is 

displayed for any read, write or compare failure detected. 

Flags 

address Specifies the memory address to be checked. 

length Specifies the number of sequential addresses to check. The 

default value is 1. 

int_var A user-created integer variable that may be used as the memory 

address to be written or length to be checked. 

imm_var An assigned user-created variable specifying an immediate 

value that may be used as a data memory address or length to 
be checked. 

See Also 

• memcopy on page 5-87 

• memfill on page 5-88 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

memcoh is used to control data and instruction cache updating during reads and 
writes. The command performs the same actions as the selections on the Memory 
Coherency Window. See "Memory Coherency Window (JTAG Targets Only)" on 
page 3-105 for more information about the coherency model terms used here. 
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Flags 

reset Reset the coherency model or one of its attributes to the default 

value. 

read Set the read memory attribute of the coherency model. 

write Set the write memory attribute of the coherency model. 

imem Specifies the instruction memory as the write attribute being set. 

dmem Specifies the data memory as the write attribute being set. 

bypass Specifies the cache is to be bypassed on data memory writes. 

iidb Specifies icache invalidate, dcache bypass on instruction 

memory writes. 

iidu Specifies icache invalidate, dcache update on instruction 

memory writes. 

iudb Specifies icache update, dcache bypass on instruction memory 

writes. 

iudu Specifies icache update, dcache update on instruction memory 

writes. 

mm Specifies the memory model is to be used for memory reads and 

data memory writes. 

phys Specifies the physical model is to be used for memory reads. 

thru Specifies the dcache is treated as write thru for data memory 

writes. 


See Also 

• “Memory Coherency Window (JTAG Targets Only)” on page 3-105 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

memcopy copies a block of memory from one address to another. The memory 
block is copied from the source address to the destination address. The number of 
bytes to copy is specified. 

Flags 

source Specifies the source memory address 

dest Specifies the destination memory address 

length Specifies the number of bytes to copy 

int_var A user-created integer variable that may be used as the memory 

address to be written 

imm_var An assigned user-created variable specifying an immediate 

value that may be used as a data memory address 

See Also 

• memchk on page 5-84 

• memfill on page 5-88 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


memfill 


— address — 


- length — 

— int_var — 


- int_var — 

- imm var — 


— imm var — 


value 


Description 

memfill fills a region of the processor's memory. The value specified is written 
starting at the specified address for the specified number of bytes. 

Flags 

address Specifies the memory address to start the fill at 

length Specifies the number of bytes to fill 

value Specifies the value to be written 

int_var A user-created variable that may be used as a memory address 

or a value to be written 

imm_var An assigned user-created variable specifying an immediate 

value that may be used as a data memory address or a value to 
be written 

See Also 


• memchk on page 5-84 

• memcopy on page 5-87 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

memfind locates the address of the first occurrence of a specified string in 
memory. A message is printed indicating successful completion of the command. 
The fourth parameter is used to hold the address where the string or value was 
found. If the string is not found, the fourth parameter will be set to the first address 
outside the specified range (address + length). 

Flags 

address Specifies the memory address to start searching. 

length Specifies the number of bytes to search. 

“string” Specifies a string of ASCII characters to be searched. 

“str_var” A user-created variable that holds a string of ASCII characters to 

be searched. 

value Specifies a string of hexadecimal characters to be searched. 

int_var A user-created variable that may be used as a memory address, 

length, or a value to be searched for. 

imm_var An assigned user-created variable specifying an immediate 

value that may be used as a data memory address or a value to 
be written. 
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Examples 

• Search for the string “TEST” starting at address OxFFCO for the next 0x200 
bytes. 

memfind OxFFCO 0x200 "TEST" 

• Search for the same string in the previous example but by specifying hex 
characters. 

memfind OxFFCO 0x200 54455354 

• Search for second occurrence of string ‘FIELLO’ within the address range 0 to 
0x200. 

create find_addr = 0 
create loop_count = 0 
create find_value = "HELLO" 
create length = 0x200 

while (find_addr < 0x200 && loop_count != 2) 
set loop_count = loop_count + 1 
if (find_addr != 0) 

set length = 0x200 - find_addr - 1 
set find_addr = find_addr + 1 
endif 

memfind find_addr length find_val find_addr 
endwhile 

if (find_addr < 0x200) 

log second occurrence found 
elseif 

log second occurrence not found 
endif 

See Also 

• memchk on page 5-84 

• memcopy on page 5-87 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


-memrwait. 


1— value —I 




Description 

memrwait displays or sets the delay used in memory read operations. This 
command is typically used to slow reads down when reading from a memory 
mapped I/O device. 

Flags 

value Specifies the delay time to set in microseconds. The valid delay 

range is 0 to 10,000,000 ps (10 seconds). The initial delay is 
zero. 

See Also 


• memwwait on page 5-92 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


►— memwwait 


L value —I 




Description 

memwwait displays or sets the delay used in memory write operations. This 
command is typically used to slow writes down when writing to a memory mapped 
I/O device. 

Flags 

value Specifies the delay time to set in microseconds. The valid delay 

range is 0 to 10,000,000 ps (10 seconds). The initial delay is 
zero. 

See Also 


• memrwait on page 5-91 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


-mpsset 


. mpsjd 


Description 

mpsset changes the current debugger context to target the specified chip. For 
more information about multiprocessor support, see “Multi-Processor Resources” 
on page 3-28 

Flags 

mpsjd Specifies which chip RISCWatch will target as the current 

context. The string must match one of the chip names initially 
defined in the MPS file. 

See Also 

• “Multi-Processor Resources” on page 3-28 
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Syntax 



Description 

pagedn scrolls the contents of a window down one page. 

If the window keyword is not specified, the last window specified for this command 

is used. It initially defaults to the Source window. 

Flags 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 

See Also 

• pageup on page 5-95 
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Description 

pageup scrolls the contents of a window up one page. 

If the window keyword is not specified, the last window specified for this command 

is used. It initially defaults to the Source window. 

Flags 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 

See Also 

• pagedn on page 5-94 
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Syntax 


parms - { 



variable 




Description 

parms allows one or more parameters to be passed into a command file when it 

is executed. 

Flags 

variable The names of variables to be created. At least one variable 

name must be specified. The variables are initialized to the 
values specified in the parameter list. If there are more variables 
specified in the parms list than there are values in the parameter 
list, the left-over variables are initialized to 0. If there are more 
values in the parameter list than there are variables in the parms 
list, the extra values are discarded. 

Examples 

• Within a command file, use the parms command to pass a memory address 
value: 

parms {mem_addr} 
read dmem mem_addr 

The variable mem_addr can now be used like any other user-created variable 
inside the command file. When RISCWatch is invoked to run this command file, 
it is now possible to pass the desired memory address into the command file 
for execution: 

rwppc mem_test{OxFFFFOOOO} 
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Note: Be sure that there is NO space between the command file name and the 
opening ‘{‘ character. Also make sure that there IS a space between the parms 
command and the opening ‘{‘ character. 

See Also 

• “Command File Parameters” on page 3-130 
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Syntax 



Description 

poll enables the user to control the various polling requests RISCWatch uses 
during debug operations. It allows the user to override the setting specified in the 
environment file. 


Flags 

id Turn background polling on or off for a given board or mps id. 

query Show the current poll settings. 

run Alter the frequency at which RISCWatch polls the target for a 

stop when running. 

status Alter the frequency at which RISCWatch polls the target for a 

change in status while stopped. 

target Target board or mps id to turn status polling on or off. See 

“Multi-Processor Resources” on page 3-28 for a description of 
valid board and mps ids. 

value Polling interval requested, in milliseconds. 
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Examples 


imm_var An assigned user-created variable specifying the requested 

polling interval, in milliseconds. 

int_var A user-created variable specifying the requested polling interval, 

in milliseconds. 


• Shut the polling off on a board in an MPS debugging session: 

poll id Boardl OFF 


5-99 




post 



Description 

post enables the user to open dialog boxes on the interface that contain specified 
information and format. This feature can be useful when used in command files to 
provide pass/fail information at the end of a test, or for providing progress 
indication that the user must acknowledge. 

Flags 

err Information specified is to be posted with an error indicator, 

note Information specified is to be posted with an note indicator, 

warn Information specified is to be posted with an warning indicator. 

string string of text to display in dialog box 

Examples 

• Here is a command file excerpt that uses the post note command to indicate 
that the command file execution has proceeded to the point that it now requires 
the user action and acknowledgment before continuing execution: 

# Board 1 init is done at this point of the file... 

POST NOTE Board 1 set up complete. Power on board 2. 

# Code below here will not execute until user confirms 

# note in dialog box 
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Syntax 


- prefer ___ src_vars - type -= - format 

- window — -i—i— option 


'—pane — 1 


L command 


I— = value —I 


Description 

prefer allows the user to customize various program settings to their liking. Some 
settings apply to windows, some to commands and others were created to allow 
for control over program wide features. 

Prefer commands are typically contained in the startup command file so that the 
designated preferences apply to the entire debug session. Prefer commands 
executed during program execution can be used to override previously set 
options. 

In particular, the src_vars setting enables the user to designate the default 
display preference for source variables. 


Flags 

src_vars This specifier is used to change the default display preference 
for source variables of different types. 

type Indicates a fundamental type of the ‘C’ programming language. 

Valid types are: 

addr integer and signed integer 

uint unsigned interger 

short short and signed short 

ushort unsigned short 

long long and signed long 
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ulong 

char 

uchar 

longlong 

ulonglong 

float 

cfloat 

double 

Idouble 

cdouble 

format 

bin 

default 

hex 

oct 

signed 

unsigned 

window 

pane 

command 

option 

addr 

base 

lines 

sign 

size 


unsigned long 

character and signed character 

unsigned character 

longlong and signed longlong 

unsigned longlong 

float point 

complex float 

double float 

long double 

complex double 

Indicates the default display format to be used for the 
fundamental type specified. Valid formats are: 

binary 

restore to default RISCWatch format 

hexadecimal 

octal 

signed decimal 
unsigned decimal 

The window keyword applies to a subset of the windows listed in 
“Window Quick Reference” on page 5-3. 

Some windows contain multiple panes of data. If a specific pane 
is specified, only its option setting will be modified. 

A valid RISCWatch command . 

The name of the option being set.Here is a list of supported 
options: 

This is the default memory address for displaying data on any of 
the memory windows. 

Used by the Custom Memory window to indicate whether data is 
to be displayed in ascii, binary, decimal or hexadecimal.. 

The number of lines used for display text when a window is first 
created. This is useful for the memory and source windows. 

Used by the Custom Memory window to indicate whether 
memory data is to be displayed in signed or unsigned format. 

Used by the Custom Memory window to indicate whether data is 
to be read and displayed as 1 , 2 or 4 byte “words.” 
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value The specific value to set a window or command option to.This 

can be left blank to erase the current option value thereby setting 
it to its default value. 


Examples 

• Change the default source variable display of all unsigned integers to 
hexadecimal. 

prefer srv_vars uint = hex 

• The following commands can be used to select whether the dis command 
displays extended or non-extendedoptocdes: 

prefer dis mnemonics = ext 
prefer dis mnemonics = non-ext 

• The following command is used indicate that execution of a command file 
should stop if an error is encountered: 

prefer exec error = stop 

• The following commands can be used to indicate if the register prefix is to 
appear for each register listed in an ASIC window: 

prefer window asic prefix = yes 
prefer window asic prefix = no 

• The following commands can be used to indicate that the Custom Memory 
window is to start display data at address 0xA0C4, read/display data as 2 byte 
words while displaying them in unsigned decimal notation: 

prefer custom addr = 0xa0c4 

prefer custom size = 2 

prefer custom base = decimal 

prefer custom sign = unsigned 

• The following command is used to force the Assembly Debug window to always 
display 20 lines of text: 

prefer debug lines = 20 

• The following command is used to fix the size of the main window command 
pane regardless of how the window is resized: 

prefer main pane maincmd fixed 

Note: If the window were resized, the command pane would remain the 
same size while the message pane would grow or shrink accordingly. 

• The following does the same for the message pane: 

prefer main pane mainmsg fixed 


5-103 




prefer 


Note: If the window were resized, the message pane would remain the same 
size while the command pane would grow or shrink accordingly. 

• The following command is used to fix the ratio of the main window command 
pane lines to its message pane lines: 

prefer main ratio = 3 

Note: If the window were resized, the two panes would grow or shrink 
accordingly but always retain the same ratio of lines to each other. 

See the sample startup command file (startup.cmd) provided with RISCWatch for 
additional examples. 
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Syntax 


-print 


. print_string. 


Description 

print takes print_string and prints it in the host window. See the fprint command 
for more details and a list of formatting options. 

Flags 

print_string This is a user definable string containing string literals, 

user-created variable names and the same type of expressions 
used in the set command. 

Examples 

• Write the print message 'R3 Test completed'. 

if (r3 != 0x12345678) 

PRINT "R3 Test completed" 
endif 

See also the Examples section of the fprint command 

See Also 

• fctrl on page 5-47 

• fprint on page 5-59 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

quit terminates the program. If the processor is running when this command is 
given and the user interface is active, a prompt is displayed to provide notification 
of the processor state and confirm the intent to terminate. 

Avoid using the quit command in a command file. If the command file is executed 
while the user interface is active, execution of the quit command will not only stop 
the command file but will also terminate RISCWatch. Use the end command 
within a command file to stop execution of the command file. 

Flags 

-f Using this flag forces termination regardless of the processor 

state. 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

read is used to read register values, four bytes of data memory, or currently 
scoped global and local source variables. The readb command is used to read 
one byte of data memory while the readh command is used to read two bytes of 
data memory. 

The first argument is used to indicate the object (memory, register, or source 
variable) to be read. If a second argument is specified, it indicates the object to be 
written using the value just read. 


Flags 

address Specifies an immediate address value from which to read data 

memory 

mem_var Any memory variable created with the assign command 
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imm_var 

reg_name 

reg_var 

src var 


int_var 


An assigned user-created variable specifying an immediate 
value that may be used as a data memory address 

A valid processor register name to be read and/or written 

An assigned user-created variable that may be used to specify a 
processor register to be read and/or written 

Any valid local or global source variable name that is currently in 
scope. The name must be preceded by a colon See “Source 
Variable Command Support” on page 3-103 for further 
information. 

A created user-created variable that may be used to hold the 
value just read 


Examples 

• Read the value of the IAR. 

read IAR 

• Read the value at memory address 0x1 FB470. 

read 0xlFB470 

• Create a user variable to represent a memory location and then use it to read 
memory. 

assign mem_addr = 0x000F701A 
read mem_addr 

• Read the contents of source ‘array[7]’ and store it in GPR R1. 

read :array[7] R1 


See Also 

• write on page 5-150 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 



reg_class 
reg_pre - 


Description 

reg is used to force a read of a specified class of registers or a subset of ASIC 
registers which share a common prefix. This is the equivalent functionality of 
pressing the Read button of the appropriate register window. 

Flags 

reg_class Specifies the class of registers to be read. See the description 
for this flag in “Command Quick Reference” located at the 
beginning of this chapter. 

reg_pre Specifies the subset of ASIC registers to be read. See the 

description for this flag in “Command Quick Reference” located 
at the beginning of this chapter. 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


reset 


core 


— chip — 

— sys — 


Description 

reset resets the processor or system. For further details about the processor 
reset, see the chapter concerning Reset and Initialization in the PowerPC 
400Series User’s Manual for the specific controller being reset. 

Note: For 6xx/7xx processors, core and chip reset are equivalent. The processor 
will be reset and stopped at instruction address 0XFFF00100. Execution of sys 
reset on 6xx/7xx processors will reset and run the processor. 


Flags 


core 

Reset 

chip 

Reset 

sys 

Reset 


the processor core. 

the processor core and ASIC. 

the entire system. 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

-restart- 

Description 

restart restarts the debug session. 

The debug session is restarted essentially by reloading the program onto the 
target. However, the debug environment remains intact. This means that any 
breakpoints that were set will still be set, and all currently selected windows and 
customizations will be preserved and their context updated as appropriate. 

Note: If the program was dynamically loaded, the breakpoint addresses will be 
recalculated based on the new location of the reloaded program. 

OS Open Note: If the program being debugged was started via a start_thread or 
an attach command, then the program will not be reloaded. The thread will be 
restarted or reattached only. This means that the data area and bss sections will 
not get reinitialized. 

See Also 


• attach on page 5-17 

• start_thread on page 5-129 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

— retstep- 


Description 

retstep returns the debugger to the previous function caller. 

This location to which the IAR is returned is effectively the contents of the current 
link register. 

Note: When stepping through code that contains no debug information, the link 
register contents could be altered by subsequent branch and link instructions. In 
these instances, retstep does not produce the desired results. Instead, a 
breakpoint should be set at the desired return location, and a run command 
executed to carry out the intended action. 

See Also 


• asmstep on page 5-12 

• bp on page 5-20 

• callstep on page 5-26 

• run on page 5-113 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 

Syntax 

run 


I— file: line - ' 


- timeout - 1 

- to - 1 — addr 




Description 

run starts the processor (JTAG target) or process (non-JTAG) running. If the 

timeout parameter is omitted, the processor/process runs until a breakpoint is 

reached or a stop command is issued. 

Flags 

to Run to a specified address or line number within a file. The 

program will run until the specifed location or a breakpoint is 
reached. 

addr Address to run to. 

filedine Filename and line number to run to. The program containing the 

specified file must already have been loaded. 

timeout The time, in seconds, that the processor/process is allowed to 

run. If the processor/process is still running after the specified 
time, the processor/process is stopped. This timeout value may 
also be specified using a created variable or an assigned 
immediate variable. 

If a run command is issued with a timeout value and then a stop 
command is issued with a timeout value, when either command 
has timed out the processor/process is stopped. 

When a run command is executed from within a command file, 
execution of the command file does not proceed until the 
processor/process has stopped. 
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Examples 

• Run the processor/process for a maximum of 10 seconds 

run 10 

• Run until the program reaches address 0xFFFF0700. 

run to 0xFFFF0700 

• Run until the program reaches line 24 of demol .c. 

run to demol.c:24 

See Also 

• stop on page 5-130 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 

Syntax 



Description 

save is used to save memory, register values, register address information, 
register field information, or the current window layout to a file. This command 
complements the load command and generates the files used by the load 
command. 

With the exception of the “bin” option, the files generated by save are human 
readable ASCII files that can be used to capture the state of processor facilities. 
Since these files are human readable, they make excellent reference material 
when debugging a problem or for providing hard-copy output. 
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Once saved, the values in these files may be loaded back into the processor, 
thereby restoring the processor's state at a later time. 


Flags 


bin 

Specifies that a portion of processor memory is to be saved in 
binary format. 

mem 

Specifies that a portion of processor memory is to be saved in 
an ASCII readable format. 

layout 

Specifies that the window layout is to be saved. 

reg 

Specifies that processor register values are to be saved. If no 
register class or ASIC prefix are specified then all registers will 
be saved. 

reg_class 

Specifies which class of registers are to be saved. 

reg_pre 

Specifies which subset of ASIC registers are to be saved. 

regfldinfo 

Specifies that all register field information is to be saved.. 
Registers containing more than one set of field definitions will 
use an instance number to differentiate each occurrence. 

reginfo 

Specifies that all register address information is to be saved. All 
register names known to RISCWatch will be saved along with 
their respective addresses. 

filename 

The name of the file to save data. 

address 

The address of memory where to start saving data. This may 
also be specified using a created variable or an assigned 
immediate variable. 

bytes 

The number of memory bytes to save. This may also be 
specified using a created variable or an assigned immediate 
variable. 

int_var 

A create variable whose value may be used in place of the 
address or bytes flags. 

imm_var 

An assign variable specifying an immediate value that may be 
used in place of the address or bytes flag. 

append 

Append the saved memory to the designated file. 


See Also 


• load on page 5-73 

• create on page 5-35 

• assign on page 5-13 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


>—►- set — argument 


L (print) J 


expression 


Description 

set is used to set a processor resource (memory or register) or RISCWatch 
variable's value to the value represented by the specified expression. 

Source variable names (program local or global variables) are preceded by a 
colon (:) to distinguish them from RISCWatch variable names. A variable is 
expanded to the corresponding expression within other commands. 

The set command is used to store computed values in memory address locations, 
registers or user-created variables. The first argument specifies where the result 
of the expression is to be stored (memory, register or variable). 

Following the first argument (or optional = sign), is the expression to be evaluated. 
This expression may be composed of registers, registers fields (logically related 
sequences of bits within a register), memory addresses, immediate values, 
user-created variables, program source variables, and various operators. See 
command expr on page 5-45 for details. 

If the very first argument of expression is the keyword (print) then this designates 
that expression is to be evaluated as a print string. This option should only be 
used when argument references a string variable. See fprint for a description of 
the syntax of print strings. 

The pseudo-variables $ERRORS and $TIMER may also be used in an 
expression. 

Memory address values which appear on the right hand side of the = sign must be 
enclosed in () so that they may be differentiated from immediate values. A 
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memory address value on the left hand side of the = sign can be written as is 
since it is not possible to assign the value of an expression to an immediate value. 

In its simplest form, the set command works exactly like a write command; writing 
a value to an object (memory, register or variable). 

However, the set command allows for complex expressions to be assigned 
whereas the write instruction does not. For example, the following command adds 
two (2) registers, divides the result by another and then shifts the result: 

set R4 = LR + RO / R17 » 4 

The result could have just as easily been assigned to a memory address location 
as opposed to the register GPR4. When using these expressions there are a few 
rules which must be kept in mind: 

1. Expressions are always evaluated from left to right; no right associative 
operators are supported (+=, -=, etc.). 

2. Registers, register fields, and address locations are treated as unsigned val¬ 
ues. 

3. When setting a variable that was created with the create or assign com¬ 
mand, the variable will increase in size, if required, to contain the full value 
determined for the right side of the equation. Variable size expansion is 
done on multiples of 4 bytes. 

4. Operations are performed based on the type of arguments being evaluated. 
The cast operator can be used to override the default size and sign. 

The following list shows the supported operators and describes their functionality: 
Operator Function 

bitwise negation(one’s complement) 

! logical negation 

arithmetic negation, subtraction 
* integer multiplication 

/ integer division 

% integer modulus 

mod integer modulus 

+ arithmetic addition 

» bit shift right 

« bit shift left 

< logical less-than 

<= logical less-than-or-equal-to 
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> logical greater-than 

>= logical greater-than-or-equal-to 

== equality 

!= inequality 

& bitwise AND 

A bitwise XOR 

| bitwise OR 

&& logical AND 

|| logical OR 

The evaluation precedence is as follows, but can be overridden using parenthesis: 

1. func(), literals, variables and pseudo-variables 

2 . () 

3. ~ ! + - 

4. * / % mod 

5. +- 

6 . »« 

7. < <= > >= 

8 . == != 

9. & 

10. A 

11. I 

12. && 

13. II 

The set command also supports limited logical operations should this sort of 
processing power be desired. The logical operations are used mainly for the 
programming constructs of command files but have been also included for the set 
command for completeness. 

One thing that must be kept in mind when using logical expressions is that their 
result is only one of two values; 0 or 1. They NEVER return any other value. The 
form of a logical expression is restricted to one basic form when it appears in a set 
command: 

argl op arg2 
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In this expression, argl and arg2 may be simple references to registers, register 
fields, memory address, immediate values or user-created variables. Each 
argument may also consist of the type of mathematical expressions described 
above. 


Flags 


argument 

expression 

logical 

mathematical 

expression 

func 

log_op 

math_op1 

math_op2 

# 


(address) | int_var | src_var | reg_name[.field_name|.#] 
reg_var 

[(] logical|mathematical [)] 
expression|expression log_op expression 
[math_op1] expression [math_op2 mathematical] 
reg_name[.fld_name|.#] | (address) | immed | variable | 
mem_var | src_var | func 
supported functions : random() 

==!=>>=< <= 

+ - ~ 

+ - * / mod % & | A « » 
ordinal bit number 


Registers specified must not be larger than 32 bits. 


Examples 

• Write a value of 0x1234 to GPRO. 

write R0 0x1234 

• Use the set command to do the same thing. 

set R0 = 0x1234 

• Set the integer variable S4 to indicate if the IAR exceeded some known memory 
address boundary. 

create S4 

assign max = 0xFFFFC14A 
set S4 = IAR > max 

In this example, if the IAR was greater than 0xFFFFC14A, variable S4 would 
get set to a 1. If not, S4 would have been set to 0. 

• Set the IA1 field of register DBCR. 

set DBCR.IA1 = 1 

• Set bit 4 of GPR17 and clear bit 12 of GPR5. 

set R17.4 = 1 
set R5.12 = 0 
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• Set local variable ‘array[7].member_i’ to the decimal value 17. 

set :array[7].member_i = 17 

See Also 

• “Command File Programming” on page 3-127 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


shell 


-expression 


L str var 


Description 

shell is used to pass a user-defined command string to the native operating 
system for execution. The command string should only contain valid host 
operating system commands. 

A special operating system call is used to create a new process for the command 
string to run under. To ensure correct command file processing, this new process 
is allowed to finish execution before control is returned to RISCWatch. Therefore, 
care must be taken as to the commands passed to the operating system using 
this command 


Flags 

expression = a string expression containing the command to be executed 

str_var = string variable created with the assign or create commands 

and containing the command to be executed. 
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Syntax 


■ showip 


Description 

showip updates the entire Debugger context based on the current Instruction 
Pointer address. All appropriate source debug windows are updated accordingly. 
For JTAG targets, the Instruction Pointer is actually the current Instruction Address 
Register (IAR). For non-JTAG targets, it is the process copy of the IAR for the 
application being debugged. 
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Note: JTAG Ethernet is the only supported JTAG target. 

TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


socket— timeout 


- value 


3 


Description 

socket displays and alters parameters associated with socket communication to a 
target. If socket is issued without value to set, the current setting is displayed, 
otherwise the setting is changed to value. 

Flags 

timeout The length of time in seconds that RISCWatch waits for 

information from a target before timing out. 

value Number of retries or timeout value in seconds 


Examples 

• Examine current timeout setting 

socket timeout 

• Set the timeout to wait for a target to 3 seconds 

socket timeout 3 


5-124 


RISCWatch Debugger User's Guide 







srcdisp 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 


srcdisp 


mixed 


i—source -i 


Description 

srcdisp changes the Source window display to show either source lines only 
(source), or mixed source/assembly lines (mixed). This is the same capability 
provided by the Source Mode groupbox on the Source window. If no parameters 
are entered, the mode is toggled. 


Flags 

mixed Sets the Source window display to show mixed source/assembly 

lines. 

source Sets the Source window display to show source lines only. 

Example 

• Set the Source window display to show mixed source/asm 

srcdisp mixed 


See Also 

“Source Window” on page 3-51 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

-srchpath 


—set dirl [dir2... dirN]- 
— add dir - 

—c[lear] - 

—q[uery] - 




Description 

srchpath determines the file search order used by the debugger to reference 
source files and executables. It is typically used when an unqualified file name is 
designated on a command. For example, if no directory path is indicated in the file 
name portion of the load file command, then the path(s) specified via the 
srchpath command are searched, in order, until the file is found. If the file is still 
not found, the current directory is also searched. Note that the current directory 
can be included anywhere in the search path by explicitly ordering it via the 
srchpath command. 

Current directory is defined as the following: 

UNIX platform The directory which began the debug session. For example, if 
you were in /home, and typed /usr/rwppc/rwppc to start 
RISCWatch, the current directory would be /home. 

Windows The Working Directory specified under the Program 

Manager’s File-> Properties pulldown for the RISCWatch 
icon. It is originally set to the same directory as the installed 
executable. 

Flags 

q[uery] Shows current directory search setting in main I/O command 

status window 
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set Sets the search path to the directories listed, in the order that 

they are entered. Note this deletes any previous setting. 

add Adds a directory to the search path at the end of the current 

setting. 

c[lear] Clears the search path setting, which will default the search to 

the current setting. 


Examples 

• Set the search path for source and executables. 

srchpath set /u/stevewin/sandbox /u/mandzak/lib 
/u/kburke/test 

If no directory path is indicated on a file name, the search path order for source 
and executables is set to 

1 ./u/stevewin/sandbox 

2. /u/mandzak/lib directory, and if still not found, 

3. /u/kburke/test. 

4. Current directory 

Note: Qualified source file names (those shown in the Source and Files 
Windows), are first checked in the designated directory. If not found, the directory 
path is removed from the name and the search continues as defined here. 

• Add a directory to the current search path. 

srchpath add /u/marsala/lib 

The search order would proceed as in the above example, except that 
/u/marsala/lib would be searched before the current directory. 

See Also 

• “Environment Resources” on page 3-5 

• load on page 5-73 
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Description 

srcline scrolls the contents of the Source window to a source line in the current 
file, highlighting the line if it contains text. 

This command is equivalent to the line command for the Source window if it is in 
'Source Only 1 display mode. It is useful if the Source window is in 'Mixed 
Source/Asm' mode, where assembly instructions are interspersed with source 
instructions. 

If the line number specified is larger than the number of source lines in the file, the 
last source line is shown at the bottom of the window. If the line number is not 
specified, the last line number specified for the command is used. The line 
variable initially defaults to 1. 

This function is also available via the input line, as described in “Input Line Usage” 
on page 3-48. 

Flags 

int_var A created user-created variable that whose value may be used 

in place of the line number. 

imm_var An assigned user-created variable specifying an immediate 

value that may be used in place of the line number. 

line Specifies the source line number to scroll to 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

» » start thread — funcname 


I_ tgrpjd _I 


Description 

start_thread initializes a source mode debug session with OS Open by 
scheduling a thread to be queued, beginning with the function designated by 
funcname. The function must have been previously linked with or dynamically 
loaded on OS Open. Threads are started using OS Open default thread 
characteristics. 

For OS Open systems that support Virtual Memory, if tgrpjd is specified, the 
function will be started in the existing thread group tgrpjd, otherwise the thread 
will be in its own newly formed thread group. 


Flags 

funcname Name of function to be started. 
tgrpjd ID of thread group for funcname. 

Examples 

• Schedule a specified thread to be queued: 

start_thread routinel 

See Also 

• attach on page 5-17 

• detach on page 5-38 

• kill thread on page 5-70 

• load on page 5-73 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


. stop 


I— timeout —I 


Description 

stop forces the processor (JTAG target) or process (non-JTAG) to stop running. 
This command is used whenever the processor/process is running and you want 
to stop it. 

If run is issued with no timeout value and no debug events set, the 
processor/process keeps running until the resident program completes execution 
or stop is issued by the user. 

stop has an optional timeout value. If a timeout value is specified and the 
processor/process is stopped, the timeout is ignored and the processor/process 
stopped normally. If a timeout value is specified and the processor/process is 
running, a timer is started and the processor/process is left running. If the 
processor/process is still running when the timer expires, the stop command is 
given to stop the processor/process. If the processor/process stops on its own 
before the timer expires, the timer is cancelled and the stop command is given to 
insure a stopped processor/process. 

If a run command is issued with a timeout value and then a stop command is 
issued with a timeout value, when either command has timed out the 
processor/process is stopped. 

Flags 


timeout 


See Also 


Specifies the number of seconds to wait before sending 
the stop command to the processor/process. 


• run on page 5-113 
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stuff 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 





OS Open 


ROM Mon 



Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


— stuff 



Description 

stuff is used to stuff a 4-byte machine instruction directly into the head of the 
instruction execution queue where it is immediately executed by the processor. 
This command must be used with caution since no error checking is done on the 
machine instruction that is given with the command. 

The machine instruction value is sent directly to the processor so an invalid 
machine instruction could produce disastrous results. It would be wise to use 
either the dis or assm command to verify the machine instruction before the stuff 
command is executed. 

It is also possible to stuff an assembly instruction into the processor using the built 
in line assembler. Simply enclose the assembly instruction in quotation marks and 
pass it to the stuff command. If the stuff command detects a string in quotes, it 
passes the string to the line assembler. If the instruction is assembled without 
error, the equivalent 4-byte machine instruction is stuffed. 

Another variation of the stuff command allows the contents of a register or 
user-create variable to be stuffed. Instead of specifying an immediate value or 
assembly instruction string, place a register or variable name after the stuff 
command. Once entered, the contents of the register or variables are read and 
then stuffed into the processor. 


Flags 

opcode An immediate machine instruction value to be stuffed. 
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assembly 

reg_name 

variable 


A valid assembly instruction string enclosed in quotation marks 
to be assembled and then stuffed. 

The name of a register whose contents are to be read and then 
stuffed. The register must not be larger than 32 bits. 

The name of a user-created variable whose contents are to be 
read and then stuffed. 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

— timer 


i— start 
_ stop 




Description 

timer allows for the timing of events from within a command file. The resolution of 
the timer is one second. 

When the timer is stopped, a status message is displayed indicating the time that 
has elapsed since the timer was started. This elapsed time value is also stored so 
that it may be printed using the $TIMER variable in a print/fprint command. It 
may also be referenced in a set expression. 


Flags 

start If the timer is stopped, this flag starts it running. If the timer is 

running, it updates the $TIMER program variable so that it may 
be printed while leaving the timer running. 

stop Stops the timer and saves the time elapsed since the start was 

given into the $TIMER program variable 
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Syntax 



Description 

top scrolls to the first line of a window, highlighting the line if it contains any text. 

If the window keyword is not specified, the last window specified for this command 

is used. It initially defaults to the Source window. 

Flags 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 

See Also 

• bot on page 5-19 
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trace 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 





OS Open 


ROM Mon 



Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: JTAG Ethernet is the only supported JTAG target. 

TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 

—trace 


save 


— buffer 


3 


— run — before — after 


1— reconstruct — filename 


- filename - 

- 

L nostop 

L nomem ^ 



- nomem - 



Description 

trace allows start and stop control of the trace function on 400Series processors. 
The command assumes that the prerequisite setup has been done prior to issuing 
the start command. For more information about the trace capabilities of 
RISCWatch, see “Using RISCTrace (400Series JTAG Processor Probe Only)” on 
page 4-2 


Flags 

run Specifies that the trace is to be started. 

reconstruct Specifies that the trace output file is to be reconstructed. The 

trace output file is designated by filename and was obtained 
using the ‘trace save buffer filename’ command. 

save Specifies that the trace is to be saved on disk. 

after Specifies the number of cycles to collect after the trigger event. 

before Specifies the number of cycles to collect before the trigger event. 

buffer Specifies the trace buffer contents are to be saved. The resulting 

file can be used on the ‘trace reconstruct' command to create a 
formatted trace. 

filename Specifies the fully qualified filename in which to save the trace. 
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nomem An optional parameter that tells the RISCTrace reconstruction 

software to use the program files that were previously loaded 
with the RISCWatch load command during the reconstruction 
process. Any address required by the reconstruction process 
and not found in the program files is read from memory on the 
user’s target. 

nostop An optional parameter that tells RISCWatch not to stop the 

processor at the completion of the trace. The user must issue 
the stop command or push the stop button to view the trace. 

Note: For processors that support forward trace only, the before cycle count should 
be set to 0 and the after cycle count should be set to a minimum of 10 cycles and a 
maximum of the total number of cycles that the JTAG processor probe can handle. For 
processors that support backtrace, the after cycle count should be set to a minimum of 
150 cycles and the sum of before and after cycles should not exceed the total number 
of cycles that the JTAG processor probe can handle. 

See Also 

• “Using RISCTrace (400Series JTAG Processor Probe Only)” on page 4-2 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 

Cmd Line Cmd File 

TTY 

• • 

• 



Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 


. unassign 


— variable 

— all- 


Description 

unassign is used to remove a variable that was prevoiusly defined with the 
assign command. 


Flags 

variable The name given to a previously assigned variable 

all Indicates all previously assigned variables will be 

unassigned 

Example 

• Assign a register to a variable and then uses the variable to initialize and read 
the register's value. Unassign the variable when the read is complete. 

assign count_reg = SPRG1 # make count_reg = SPRG1 

set count_reg =0 # init count register 

read count_reg # i.e. read SPRG1 

unassign count_reg # remove assignment 

• Assign an immediate value to a variable which is then used to initialize the 
value of a register. Unassign this variable and all others that may exist. 

assign reg_val = 0x11223344 
set SPRGO = reg_val 
unassign all 
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See Also 


• assign on page 5-13 

• uncreate on page 5-139 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 


Syntax 



Description 

uncreate is used to remove a variable that was previously defined with the create 
command. 

Flags 

variable 

all 

Examples 

• Uncreate a variable named cr_var1. 

create cr_varl = 0x1234 
uncreate cr_varl 

• Create two variables, i and j, and use them to calculate a value to write to 
GPRO. When complete, removes all previously created variables. 

create i # create variable i 

create j # create variable j 

set i = (0x12345678) # read memory into i 

set j = i - IAR # subtract IAR from i 

write R0 j # write value of j to GPR 0 

uncreate all 

See Also 

• create on page 5-35 

• unassign on page 5-137 

5-139 


Name of the immediate variable that was previously created. 
Indicates all previously created variables will be uncreated 







unload 



Syntax 



Description 

unload removes the program specified by filename from the debugger. It also 
removes any breakpoints set within the specified program context. However, any 
loaded program will continue to reside in target memory. 

Also, this command applies only to files loaded to perform source level debug via 
the load file or load host command option. 

Flags 

all Unloads all programs currently loaded in the debugger. 

filename Specifies program to be unloaded. If unqualified, the file 

unloaded will be determined by the srchpath settings currently 
in effect. 

Seae Also 

• load on page 5-73 
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up 



401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 


I— lines 


I— window - 


pane 


Description 

up scrolls the contents of a window up a number of lines from the top line visible in 
the window. 

If the number of lines specified is larger than the number of lines from the top of 
the window, the first line is shown at the top of the window. If the window keyword 
is not specified, the last window specified for this command is used, window 
initially defaults to the Source window. If neither the lines variable nor the window 
keyword is specified, the last lines value and window specified for the command 
are used. The lines variable initially defaults to 1. 

Flags 

lines Specifies the number of lines to be scrolled up in window 

window The window keyword applies to a subset of the windows listed in 

“Window Quick Reference” on page 5-3. The items marked with 
an asterisk (*) indicate the subset of valid window keywords for 
this command. 

pane See list of pane keywords in “Command Quick Reference” on 

page 5-4 (page 5-3). 
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Examples 

• Scroll up two lines in a window previously specified, or the Source window if 
none was previously specified. 

up 2 

• Scroll up six lines in the Breakpoints window. 

up 6 break 

See Also 

• down on page 5-41 
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varinfo 



Description 

varinfo changes the Local or Global variable window display to show type, 
address, and size information for each visible variable. It also allows a user to 
specify the method used to read variable data. This is the same capability 
provided by the Display Information groupboxes on the Variable Configuration 
window. 

Flags 

locals Specifies Locals variable window 

globals Specifies Globals variable window 

all Shows the address, size and type for each variable 

none Shows no address, size and type information for each variable 

addr Shows the address of each variable 

rdblk Specifies that the variable information is to be read as a block of 

contiguous data. 

size Shows the size of each variable 

type Shows the type of each variable 
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Example 

• Set the Locals window display to show address and type information for each 
visible variable 

varinfo locals addr 
varinfo locals type 

• Change the Globals window display to show address information only, and 
specify that the varaibles are each to be read as contiguous data blocks. 

varinfo globals none # clears current settings 
varinfo globals addr 
varinfo globals rdblk 

See Also 

“Reading and Writing Memory” on page 3-104 
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varvis 



Syntax 



Description 

varvis changes the visibility of variables on the Locals or Globals variable 
windows. This is the same capability provided by the relevant pushbuttons on the 
Variable Configuration window. 

Note: Initially, RISCWatch will default to all local variables being visible, and all 
global variables being invisible. These defaults could be changed by putting the 
appropriate varvis command entries in a startup command file after a file is 
loaded. 

Flags 

locals Specifies Locals variable window 

globals Specifies Globals variable window 

src_var Any valid local or global source variable name that is currently in 

scope. The name must be preceded by a colon See “Source 
Variable Command Support” on page 3-103 for further 
information. 

vis Make the variable(s) visible 

invis Make the variable(s) invisible 

Example 

• Set the Globals window display to show all variables 

varvis globals vis 
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• Show only the global variable show_me in the Global window display. 

varvis globals invis #clear previous settings 
varvis :show_me vis 

See Also 

“Variable Configuration Window” on page 3-83 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 
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• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 


. view 


filename 


Description 

view allows for a specified file to be viewed. The specification of the filename is 
optional. If it is not specified, a file dialog box is presented for the user to navigate 
the directory structure and select a file to view. This functionality is only available 
when you are using the graphical user interface, not from within a command file. 

Once a file has been selected, a window is displayed and the contents of the file 
are displayed within it. The file may be viewed but not edited. Text size can be 
adjusted using the menubar Font pulldown. To search for specified text, enter it in 
the ’Find string’ field and press the Enter key or click on the Find button. To 
perform a backward or case-sensitive search, click on the appropriate check 
boxes. To go to a specific line in the file, enter the line number in the 'Goto line’ 
field and press the Enter key. To go to the last line, enter "last" or "bottom". 

This command is equivalent to using the View option of the File pull-down menu. 
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401/5x 

403x 

602 

603x 

604x 

7xx 

JTAG 

• 

• 

• 

• 

• 

• 

OS Open 

• 

• 

• 

• 

• 

• 

ROM Mon 

• 

• 

• 

• 

• 

• 


Modes 


Cmd Line Cmd File 

TTY 

• • 



Syntax 


window 


window 


cfss 

udw 


I— :mps_id —I \—:reg_pre —I 

- filename — 


I_ :mps_id_\ 

inspect— filename" :line_num:variable 


regfld 


I _ :mps_id J 


reg_name 


-■.instance 


Description 

window allows the user to either bring up a new window instance or to surface an 
existing window from the command line interface. For new windows, this is the 
same capability provided by the main menu pulldowns. For existing windows that 
can not have multiple instances, it provides the same function as the Window List 
pulldown. When used for windows that already exist and can have multiple 
instances, a new instance is created when the command is invoked. 


Flags 

Specifies the Command File Window. 

Specifies a Variable Inspect Window. 

Specifies a Register Field Window. 

Specifies a User Defined Window. windowThe window keyword 
applies to a subset of the windows listed in “Window Quick 
Reference” on page 5-3, including items marked with an asterisk 
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cfss 

inspect 

regfld 

udw 







window 


filename 

line_num 

variable 

reg_name 

reg_pre 


instance 


(*). The command will give an error if the window keyword 
specified is not valid for the command. 

The name of the file containing the desired variable to inspect. 
Note it must be enclosed in quotations. 

The specific line number within a file that contains the desired 
variable to inspect. 

The name of the variable to inspect. 

A valid processor register whose field window is to be displayed. 

When ASIC is specified for window, this specificies a unique 
ASIC window which contains the registers with the specified 
prefix. See the description for this flag in “Command Quick 
Reference” located at the beginning of this chapter. 

A register or window instance number. 


mps_id The mps id of the window. 


Examples 

• Bring to the foreground the source window on Board 2 while in Board 1 context. 

window source:Board_2 

• Bring up a source window in the current context. 

window source 

• Bring up a second instance of the debug window in the current context, 
assuming one is already active. 

window debug 

• Bring up an inspect window to look at the contents of variable my_struct.name, 
found on line 24 of file testit.c : 

window inspect :"testit.c":24:my_struct.name 

• Bring up a user defined register field window in an MPS environment. 

window regfId:Board_2 MSR:2 
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Note: TTY mode is available only on RS/6000 and Sun workstations. 
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write 


Description 


write is used to write a value to either a register, a 4-byte data memory location, a 
4-byte instruction memory location, a source variable, or to a breakpoint register. 

writeb is used to write a 1-byte data memory location, while writeh is used to 
write a 2-byte data memory location. 


write reg Write a new value to a register. Note the reg keyword is optional. 


write dmem Write a new value to a data memory location. Up to four (4) 
bytes of data can be written to a valid address. 

writeb dmem Write a new value to a data memory location. One (1) byte of 
data can be written to a valid address. 


writeh dmem Write a new value to a data memory location. Two (2) bytes of 
data are written to a valid address. 

write imem Write a new value to an instruction memory location. write tlb 
Write a new value to an entry of a unified TLB. 


Flags 


dmem 

imem 

reg 

address 
ascii value 


expression 

mem_var 

int_var 

imm var 


reg_name 

reg_var 


Write to a data memory address. 

Write to an instruction memory address. 

An optional parameter indicating a write to an architected 
register in the chip. 

Specifies an immediate value which represents the memory 
location to be written. 

Specifies an immediate ASCII string value to be written. It must 
be enclosed in double quotes, The null terminator character is 
not written. 

Additional information required by the specific write command 
issued. 

Any memory variable created with the assign command. 

A created user-created variable that may be used as the 
memory address to be written or as the value to be written. 

An assigned user-created variable specifying an immediate 
value that may be used as the memory address to be written or 
as the value to be written. 

A valid processor register name to be read and/or written. 

An assigned user-created variable that may be used to specify a 
processor register to be read and/or written. 
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src_var Any valid local or global source variable name that is currently in 

scope. The name must be preceded by a colon See “Source 
Variable Command Support” on page 3-103 for further 
information. 

str_var Specifies a user created string variable containing the ASCII 

data to be written. The null terminator character is not written. 

value An immediate value to be written to the specified memory 

address or register. 


Examples 

• Write OxDEADBEEF to the IAR register. 

write reg IAR OxDEADBEEF 

• Write 0x11112222 to GPRO. 

write R0 0x11112222 

• Write the contents of SRRO to R14. 

write R14 SRRO 

• Write OxDEADBEEF to address OxFFFFFFFO. 

write dmem OxFFFFFFFO OxDEADBEEF 

• Write an immediate hex value bit for bit into a 64-bit register: 

write FPRO 0x1234567812345678 

• Write an immediate value specified in scientific notation into a 64-bit register in 
floating point format: 

write FPRO 1.23456e+002 

• Write the contents of GPR3 to memory at address OxFFFFOOOO. 

write dmem OxFFFFOOOO R3 

• Write the contents of the user-created variable varl into memory at address 
OxFFFFOOOO. 

create varl = OxDEADBEEF 
write dmem OxFFFFOOOO varl 

• Write the contents of the user-assigned variable mem_val to the address found 
in the user-assigned memory variable mem_addr: 

assign mem_addr = (0xABCD1234) 
assign mem_val = OxDEADBEEF 
write mem_addr mem_val 

• Write the contents of the user-assigned variable, mem_val, to the address 
found in the user-assigned register variable, mem_reg, which points to the R0 
register. 
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assign mem_val = OxDEADBEEF 
assign mem_reg = RO 
set RO = Oxl234ABCD 

write mem_reg mem_val 

• Write the contents of source global variable ‘ptr->member_a’, defined in file 
‘test.c’, to the immediate value 0x12345678: 

write : “test. c“: ptr->member_a 0x12345678 

• Write the ASCII value “KJ The Porcupine” into memory starting at address 
0x500: 

write imem 0x500 "KJ The Porcupine" 

Note: Any of the write dmem examples are also valid for write imem, just 
replace the word dmem in each example to imem. 

See Also 

• read on page 5-107 
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Appendix A. Interfacing RISCWatch to a Target Board 

This appendix describes the requirements for connecting RISCWatch to a 
PowerPC processor on a target development board. For the list of PowerPC 
processors, consult the README file for this version of RISCWatch. 


IEEE 1149.1 (JTAG) Port 

For RISCWatch to interface to the JTAG port on a PowerPC processor, a 16-pin 
male 2x8 header connector, shown in Figure A-1, must be available on the target 
development board. 


15 


KEY 


u 

o.r 


'T 


16 


i___i 

—►lo.rU— 


Figure A-1. JTAG Pleader Connector (top view) 


Note that position 14 of the header connector on the target development board 
should not contain a pin. The mating receptacle supplied with a RISCWatch JTAG 
adapter cannot be installed if pin 14 has not been removed from the header. 

This header connects the RISCWatch JTAG hardware (parallel port adapter or 
processor probe) to the JTAG port of the PowerPC processor on the target 
development board, using the electrical connections described below. The header 
should be placed as close as possible to the processor to insure signal integrity. 

Table A-1 describes the header connections for the PowerPC 400Series 
processors, and Table A-2 provides the same for the PowerPC 6xx/7xx 
processors. Consult the specific processor manual for the processor pin number if 
required. 
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Table A-1. PowerPC 400Series JTAG Interface Connections and Resistors 


Header Pin I/O 

Signal Name 

Board 

Resistor 1 

1 Out 

TDO 


2 

No Connect 


3 In 

TDI 

10Kfi PU 

4 

No Connect 


5 

No Connect 


6 

+POWER 2 

1KL1SR 3 

7 In 

TCK 

10Kfi PU 

8 

No Connect 


9 In 

TMS 

10Kfi PU 

10 

No Connect 


11 In 

HALT 

10Kfi PU 

12 

No Connect 


13 

No Connect 


14 

KEY 


15 

No Connect 


16 

GND 



1 PU = pullup, PD = pulldown, SR = series 

2 The +POWER signal is sourced from the target development board and is used as a reference signal by the 
RISCWatch Processor Probe. The voltage presented on this pin should indicate the voltage level of the 
processor I/O. Newer versions of the processor probe will adjust voltage levels on input pins to the 
processor accordingly. 

3 This 1K ohm series resistor provides short circuit current limiting protection only. If the resistor is present, it 
should be 1K ohm or less. 

Note: Pin 4 should be connected to TRST on the PPC405GP/PPC405CR 
processors and should be pulled up with a 10K resistor. 
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Table A-2. PowerPC 6xx/7xx JTAG Interface Connections and Resistors 


Header Pin I/O 

Signal Name 

Board 

Resistor 1 

1 Out 

TDO 


2 



3 In 

TDI 

10Kfi PU 

TDI 

1KO PD 

4 In 

TRST 

10Kfi PU 

5 



6 


IKflSR 3 

7 In 

TCK 

10Kfi PU 

8 



9 In 

TMS 

10Kfi PU 

10 

No Connect 


11 In 

SRESET 

10Kfi PU 

12 

No Connect 


13 In 

HRESET 

10Kfi PU 

14 

KEY 


15 Out 

CHECKSTOP 

10Kfi PU 

CKSTPOUT 

16 

GND 


N/A In 

QACK 4 

1KO PD 

L2_TEST_CLK 

10Kfi PU 

L1_TEST_CLK 

LSSD_MODE 

ARRAY_WR 


= pullup, PD = pulldown, SR = series 

2 The +POWER signal is sourced from the target development board and is used as a reference signal by the 
RISCWatch Processor Probe. The voltage presented on this pin should indicate the voltage level of the 
processor I/O. Newer versions of the processor probe will adjust voltage levels on input pins to the 
processor accordingly. 

3 This 1K ohm series resistor provides short circuit current limiting protection only. If the resistor is present, it 
should be 1K ohm or less. 

4 lf the target development board does not use this signal, the board must have a 1 Kfl PD connected to this 
pin. This signal allows the processor to enter the soft stop state. Otherwise, the target development board 
must provide the proper logic, so that the QACK goes Low in response to a QREQ. If the proper logic is not 
provided, the processor will not be able to enter the soft stop state. 


The HRESET, SRESET, and TRST signals from the RISCWatch Processor 
Interface Assembly connector must be logically ORed with the HRESET, 
SRESET, and TRST signals that connect to the processor on the target 
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development board. They cannot be “dotted” or “wire-ORed” on the board. In 
addition, the ORed signals should only reset the processor and no other devices 
on the target board. 

For further information concerning RISCWatch support for processor reset, see 
“Processor Reset Window (JTAG Targets Only)” on page 3-138. 


Trace Status Port (400Series JTAG Processor Probe Only) 

A 20-pin male 2x10 header connector (3M 3592-6002 or equivalent) is 
recommended for connecting to the Trace Status Port of a PowerPC 400Series 
processor. The connector outline, shown in Figure A-2, and the signal 



Figure A-2. RISCTrace Pleader (top view) 

descriptions in Table A-3 match the requirements of RISCTrace, when used with 
the RISCWatch processor probe with RISCTrace option or the TracePort Analyzer. 
The connector for RISCTrace should be placed as close as possible to the 
processor to insure signal integrity. For the 405, it is recommended that the trace 
signals have 33 ohm source terminators and that the connections from the trace 
pins to the trace connector be of equal length. 

There are seven Trace Status(TS) signals, TS0:6, on the PPC403GA and 
PPC403GC/GCX processors. There are six Trace Staus signals, TS1:6, on the 
PowerPC 401 Core processors. There are eight Trace Status signals, TS1:20, 
TS1:2E and TS3:6, on the PowerPC 405 Core processors. These signals are 
sampled on the rising edge of the trace clock. 
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Table A-3 describes the assignment of the TS signals and the trace clock (TrcClk) 
output to the header pins: 


Table A-3. RISCTrace Header Pin Description 


Pin 

Signal Name 

Pin 

Signal Name 

1 

No Connect 

11 

No Connect 

2 

No Connect 

12 

TS10 

3 

TrcClk 

13 

TS0/TS2O 

4 

No Connect 

14 

TS1/TS1E 

5 

No Connect 

15 

TS2/TS2E 

6 

No Connect 

16 

TS3 

7 

No Connect 

17 

TS4 

8 

No Connect 

18 

TS5 

9 

No Connect 

19 

TS6 

10 

No Connect 

20 

GND 


For additional information, see “Using RISCTrace (400Series JTAG Processor 
Probe Only)” on page 4-2. 

Note that TrcClk is the system clock for the PPC403GA/GC/GCX processors. For 
the 401 and 405 based processors, TrcClk is a processor output. 
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JTAG and Trace Connector Requirements 

1. Individual JTAG and Trace connectors must be placed as close as possi¬ 
ble to the processor and close to each other. It is highly recommended 
that individual JTAG and Trace connectors be placed parallel to each 
other with the orientation exactly as shown below 



Figure A-1. RISCTrace 2 xIO and RISCWatch 2x8 Headers 


2. Support for individual JTAG and Trace connectors is being replaced by 
one combined Mictor connector for better electrical and mechanical char¬ 
acteristics as shown below. 


Table A-1. Mictor Connector Signal Assignments 
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Table A-1. Mictor Connector Signal Assignments 


PIN 

PPC401 

PPC403 

PPC405 

Notes 

24 

tsth “ 




26 

TSO 

TS20 



28 

TS1 

TS1 

TS1E 


30 

TS2 

TS2 

TS2E 


32 

TS3 

TS3 

TS3 


34 

TS4 

TS4 

TS4 


36 

TS5 

TS5 

TS5 


38 

TS6 

TS6 

TS6 



Target Monitor Debugging 

In addition to RISCWatch communicating directly to processor hardware via a 
JTAG connection, RISCWatch can also communicate with target monitor software 
included in both the IBM OS Open real-time operating system and the PowerPC 
evaluation kit ROM monitor. This communication can must use an Ethernet 
(TCP/IP) connection. 

Custom target monitors can also be created using the available Board Support 
debug libraries supplied in the PowerPC evaluation kits. This provides the ability 
to port the software debug capabilities of RISCWatch to custom board solutions. 

For further information, consult the OS Open and evaluation kit documentation 
listed in “Related IBM Publications” on page xxiv. 
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Appendix B. Register Definition File (Outdated) 

This appendix describes the file format of the Register Definition File (RDF). 
Starting with RISCWatch 4.3, the Processor Configuration File should be used in 
place of the RDF. In addition to supporting the RDF features, the PCF format 
enables users to define their own chips, macros and IMR registers. Please refer to 
section “Processor Configuration File (PCF)” on page 3-10 for details on how to 
convert your Register Definition File to the PCF format. 

Register Definition File 

When RISCWatch is first started, the environment file (rwppc.env) is read to 
determine the debug environment. The PROC environment variable is used by 
RISCWatch to enable a unique set of predefined processor registers. For 
example, if the PROC environment variable indicates a 401 core (ie. 401 ml), 
RISCWatch will only enable the SPR registers defined for that core processor. 

By using the REG_FILE environment variable, users can identify a customized 
Register Definition File. This file, created by the user prior to starting RISCWatch, 
contains additional register definitions that RISCWatch will add to its list of valid 
processor registers. 

The Register Definition File is searched for using the following rules: 

• If the file name is qualified (directory path indicated), the file search is 
performed using the specified directory only. 

• If the name is not qualified, the file search is performed using the directory 
paths designated with the RISCWatch SEARCH_PATH environment 
variable. If not found, the current directory is searched. 

File Syntax 

The Register Definition File is an ASCII file that can be created with any text 
editor. The file is identified to RISCWatch via the REG_FILE environment variable, 
and must have a file extension of “.reg”. A sample Register Definition File, called 
rwppc.reg, is provided with RISCWatch and contains comments which detail the 
required syntax described here. 

The general syntax rules are as follows: 

1. The “#” character denotes the start of a comment. All text following the “#” 
character on a given line will be ignored. 

2. Blank lines are allowed and will be ignored. 

3. Any error detected during the processing of the Register Definition File 
will surface an error message which will be saved in the RISCWatch log 
file and execution will terminate. 
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The following sections define the complete list of valid line entries. Unless 
specifically stated otherwise, a record is defined to be a single line contained in 
the Register Definition File. 

DCR Register Definitions 

A DCR register definition identifies a unique register that can be accessed via the 
PowerPC mtdcr and/or mfdcr instructions. Each DCR record must adhere to the 
following syntax: 

DCR name number size type [VOLATILE] 

Where: 


• DCR indicates a new DCR register definition and must appear in 
uppercase. 

• name indicates the name of the register being defined and must not 
exceed 6 characters. 

• number indicates the DCR register number, as defined by the PowerPC 
mfdcr or mtdcr instruction. Valid numbers can be expressed in hex (leading 
“Ox” or “OX'), octal (leading “0”), or decimal. 

• size is a decimal number indicating the number of bits in the register. 

• type indicates the type of access allowed. Valid types are “R” (read only), 
“W” (write only), or “RW” (read and write). 

• VOLATILE is an optional keyword which indicates this register will change 
its value after a read operation is performed. It must be entered in 
uppercase. RISCWatch users must issue an explicit read to display the 
contents of a volatile register. Having the auto-update mode enabled on a 
window containing these registers will not cause them to be read during 
the update. 

Examples: 

DCR BRCRHO 0x70 32 RW 
DCR BEAR 0x090 32 R 

DCR records are valid for PowerPC 400 Series processors only. 
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SPR Register Definitions 

An SPR register definition identifies a unique register that can be accessed via the 
PowerPC mtspr and/or mfspr instructions. Each SPR record must adhere to the 
following syntax: 

SPR name number size type [VOLATILE] 

Where: 


• SPR indicates a new SPR register definition and must appear in 
uppercase. 

• name indicates the name of the register being defined and must not 
exceed 6 characters. 

• number indicates the SPR register number, as defined by the PowerPC 
mfspr or mtspr instruction. Valid numbers can be expressed in hex (leading 
“Ox” or “OX’), octal (leading “0”), or decimal. 

• size is a decimal number indicating the number of bits in the register. 

• type indicates the type of access allowed. Valid types are “R” (read only), 
“W” (write only), or “RW” (read and write). 

• VOLATILE is an optional keyword which indicates this register will change 
its value after a read operation is performed. It must be entered in 
uppercase. RISCWatch users must issue an explicit read to display the 
contents of a volatile register. Having the auto-update mode enabled on a 
window containing these registers will not cause them to be read during 
the update. 

Examples: 

SPR estat 0x03d4 32 RW 
SPR DEAR02 0x03d5 32 R 

SPR records are valid for PowerPC 400 Series processors only. SPR records 
allow users to create their own register names of any core SPR registers. They 
provide a form of register name aliasing which can be used in conjunction with 
FLDDEF records to customize the display of core registers. 
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MMIO Register Definitions 

An MMIO register definition identifies a unique ASIC memory-mapped register 
that can be accessed via the PowerPC load and/or store instructions. Each MMIO 
record must adhere to the following syntax: 

MMIO name address size type [access] [VOLATILE] 

Where: 


• MMIO indicates a new memory-mapped register definition and must 
appear in uppercase. 

• name indicates the name of the register being defined and must not 
exceed 6 characters. 

• address is a hex number indicating the address to use on the appropriate 
PowerPC load or store instruction. A leading “Ox” or “OX’ is allowed, but not 
required. 

• size is a decimal number indicating the number of bits in the register. 

• type indicates the type of access allowed. Valid types are “R” (read only), 
“W” (write only), or “RW” (read and write). 

• access is an optional parameter which is used on JTAG ethernet and JTAG 
parallel port RISCWatch targets. It is a decimal number which indicates the 
access size, in bits, RISCWatch must use when reading or writing this 
memory location. The access size should be a multiple of eight, with each 
multiple identifying a unique PowerPC load/store instruction to use. For 
example, an access size of “16” instructs RISCWatch to read the register 
by executing the “load halfword” PowerPC instruction. Specifying an 
access size will override any access size settings made with the memacc 
command. If no access size is specified, RISCWatch will use the access 
size defined for the memory region. See memacc on page 5-81 for 
information about how to set up a unique memory region access size. 

• VOLATILE is an optional keyword which indicates this register will change 
its value after a read operation is performed. It must be entered in 
uppercase. RISCWatch users must issue an explicit read to display the 
contents of a volatile register. Having the auto-update mode enabled on a 
window containing these registers will not cause them to be read during 
the update. 

Examples: 

MMIO ASIC01 0000A000 32 RW 
MMIO ASIC02 0000A004 32 RW 8 
MMIO records are valid for all PowerPC processors. 
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ALIAS Definitions 


An ALIAS definition identifies a new name for one of the predefined processor 
registers. Each ALIAS record must adhere to the following syntax: 

ALIAS new_name = old_name 
Where: 


• ALIAS indicates a new ALIAS register definition and must appear in 
uppercase. 

• new_name indicates the name of the register being defined and must not 
exceed 6 characters. 

• old_name indicates a valid register name for the target processor, which 
may include any previously processed SPR, DCR, or MMIO records. 

Examples: 

ALIAS PC = IAR 

ALIAS GPRO = RO 

ALIAS records are valid for all PowerPC processors. 

Register Field Definitions 

Register field definitions span multiple lines of the file and are used to indicate 
field names for contiguous groups of bits in a register. Each register field definition 
must adhere to the following syntax: 

FLDDEF reg_name 

field_name start_bit size 


ENDFLDDEF 


Where: 


• FLDDEF indicates the start of a new register field definition and must 
appear in uppercase. 

• reg_name indicates a valid register name for the target processor, which 
may include any previously processed SPR, DCR, or MMIO records. 
Subsequent field_name records will be assigned to this register. 

• field_name indicates the name given to a contiguous group of register bits 
and must not exceed 6 characters. This record is only allowed between 
enclosing FLDDEF and ENDFLDDEF records. 

• start_bit is a decimal number which indicates the first bit of the register 
associated with this field name. A value of zero indicates the first bit of the 
register. This value should not exceed the bit size of the register. 
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• size is a decimal number which indicates the total number of bits assigned 
to this field name. The sum of start_bit and size should not exceed the total 
bit size of the register. 

• .indicates one or more field_name records which are used to completely 

define field names to all bits of the designated register. 

• ENDFLDDEF indicates the end of a register field definition and must 
appear in uppercase. 

Example: 

FLDDEF estat 

mcheck 0 4 
progexc 4 3 
resvOa 7 1 
storexc 8 2 
resvOb 10 22 
ENDFLDDEF 

Register field definitions are valid for all PowerPC processors. They are generally 
used to assign bit field names to user defined registers and core processor 
registers which do not have any predefined bit fields. 
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